<?php

declare(strict_types=1);

namespace App\Domain\Auth;

/**
 * The result of token + impersonation resolution.
 *
 * Attached to the PSR-7 request as `principal` after the auth middleware
 * stack runs. RbacMiddleware reads `role`; controllers read whichever of
 * `userId` / `reporterId` / `consumerId` is relevant.
 *
 * `userId` is set when:
 *  - the token is a `service` token and impersonation produced a user, or
 *  - the token is an `admin` token bound to a user (none in M03, but the
 *    field is present so M14 can add it without churn).
 *
 * `role` is set for `admin` tokens (the token's own role) and after
 * service-impersonation (the impersonated user's role).
 *
 * `userIsLocal` is set whenever `userId` is — its value is the matching
 * user record's `is_local` flag. AuditContextMiddleware reads it to
 * classify `actor_via` as `oidc` vs `local` for impersonated rows
 * (SEC_REVIEW F11).
 */
final class AuthenticatedPrincipal
{
    public function __construct(
        public readonly TokenKind $tokenKind,
        public readonly ?int $userId,
        public readonly ?Role $role,
        public readonly ?int $reporterId,
        public readonly ?int $consumerId,
        public readonly int $tokenId,
        public readonly ?bool $userIsLocal = null,
    ) {
    }
}
