AuthContext

The trusted answer to "who is making this request, and may we trust it?" — an {@see AuthState} and, when authenticated, the {@see Actor} it resolved to. This is the *product* the whole package exists to make: a credential verifier turns a raw {@see Credential} into one of these, and the policy layer authorises against it. It carries the scope helpers so a caller can ask "may this * request do X?" without first unwrapping (and null-checking) the actor. Immutable by construction.

public function __construct(?Milpa\Auth\Actor $actor, Milpa\Auth\AuthState $state, array $metadata = [], ?Milpa\Auth\PermissionSet $permissions = null):

Parameters

public static function anonymous(): self

A context for a request that presented no credential: no actor, state {@see AuthState::Anonymous}.

public static function authenticated(Milpa\Auth\Actor $actor): self

A context for a request whose credential verified into `$actor`: state {@see AuthState::Authenticated}.

Parameters

public static function invalid(?string $reason = null): self

A context for a request that presented a credential which was rejected: no actor, state {@see AuthState::Invalid}, and `$reason` recorded under the `reason` metadata key. Distinct from {@see self::anonymous()} on purpose — a bad credential is not the same as no credential.

Parameters

public function isAuthenticated(): bool

Whether this request authenticated to an actor — true only in the {@see AuthState::Authenticated} state.

public function hasScope(string $scope): bool

Whether the request's actor holds `$scope`. Fail-closed: with no actor (anonymous or invalid) this is always false, and otherwise it delegates to {@see Actor::hasScope()}.

Parameters

public function hasAnyScope(array $scopes): bool

Whether the request's actor holds at least one of `$scopes`. Fail-closed: with no actor this is always false; otherwise it delegates to {@see Actor::hasAnyScope()}.

Parameters

public function permissions(): ?Milpa\Auth\PermissionSet

The resolved {@see PermissionSet} for this request, or null when none was resolved (the flat-scope fallback in {@see self::can()} still works).

public function withPermissions(Milpa\Auth\PermissionSet $permissions): self

A copy of this context carrying $permissions — used by the enforcement layer after it resolves.

Parameters

public function can(string $resource, string $action, ?string $namespace = null): bool

Whether the request's actor may perform `$action` on `$resource` (optionally within `$namespace`). Uses the resolved {@see PermissionSet} when present; otherwise falls back to the flat-scope check, so `can('posts','read') ≡ hasScope('posts:read')` for a flat-scope-only actor. Fail-closed: with no actor (anonymous/invalid) this is false.

Parameters