Reference
Overview

Reference overview

Every symbol shipped by padosoft/laravel-iam-contracts lives under the Padosoft\Iam\Contracts\
namespace. This page is the index; each namespace has its own deep page with full signatures, the why,
implementors/consumers, and worked examples.

The namespace map

flowchart TB ROOT["Padosoft\\Iam\\Contracts"] ROOT --> SUP["Support\\\\ — SubjectRef"] ROOT --> AUTH["Authorization\\\\ — AuthorizationEngine"] ROOT --> CRY["Crypto\\\\ — KeyProvider, SecretCipher, TokenSigner"] ROOT --> ASR["Assurance\\\\ — Aal, AssuranceProvider, StepUpProvider, FactorVerifier, + DTOs"] ROOT --> GOV["Governance\\\\ — FeatureScope, FeatureKey, ScopeLevel, FeatureContext"] ROOT --> IDN["Identity\\\\ — SessionRegistry, SessionRef, SessionMeta"] ROOT --> DEL["Delegation\\\\ — ActorRef, DelegationChain, DelegationGrant, TokenExchanger, DelegatedAuthorizationEngine"]

Everything at a glance

Symbol	Kind	Namespace	One line	Page
`SubjectRef`	`final readonly` (Stringable)	`Support`	`type:id` reference to any PDP subject	Authorization
`AuthorizationEngine`	interface	`Authorization`	the pluggable PDP: `check` + reverse-index	Authorization
`KeyProvider`	interface	`Crypto`	DEK envelope wrap/unwrap/generate	Crypto
`SecretCipher`	interface	`Crypto`	encrypt/decrypt/shred secrets (crypto-shredding)	Crypto
`TokenSigner`	interface	`Crypto`	issue/parse JWT (ES256) + JWKS + rotate	Crypto
`Aal`	enum `string`	`Assurance`	NIST 800-63B assurance level (aal1/2/3)	Assurance
`AssuranceProvider`	interface	`Assurance`	current AAL of a session	Assurance
`StepUpProvider`	interface	`Assurance`	step-up challenge lifecycle	Assurance
`FactorVerifier`	interface	`Assurance`	verify one auth factor (TOTP/passkey)	Assurance
`StepUpPurpose`	`final readonly`	`Assurance`	action + required AAL for a step-up	Assurance
`StepUpChallenge`	`final readonly`	`Assurance`	issued challenge (id, method, expiry)	Assurance
`StepUpResult`	`final readonly`	`Assurance`	step-up outcome (success, resulting AAL)	Assurance
`FeatureScope`	interface	`Governance`	gate/scope a governance feature	Governance
`FeatureKey`	enum `string`	`Governance`	which governance feature	Governance
`ScopeLevel`	enum `string`	`Governance`	cascade level (layer/app/role/user)	Governance
`FeatureContext`	`final readonly`	`Governance`	evaluation context for a feature scope	Governance
`SessionRegistry`	interface	`Identity`	revocable server-side sessions	Identity
`SessionRef`	`final readonly` (Stringable)	`Identity`	wraps the `sid` binding tokens to a session	Identity
`SessionMeta`	`final readonly`	`Identity`	metadata a session opens with	Identity
`ActorRef`	`final readonly` (Stringable)	`Delegation`	the acting agent of a delegation (`act` sense)	Delegation
`DelegationChain`	`final readonly`	`Delegation`	ordered actor chain, RFC 8693 nested `act`	Delegation
`DelegationGrant`	`final readonly`	`Delegation`	the user’s consented delegation (scopes, purpose, TTL)	Delegation
`DelegationGrantStatus`	enum `string`	`Delegation`	Active/Suspended/Expired/Revoked (fail-closed)	Delegation
`AgentDescriptor`	`final readonly`	`Delegation`	registered agent: operator, owner, max scopes, status	Delegation
`AgentStatus`	enum `string`	`Delegation`	Pending/Active/Suspended/Retired lifecycle	Delegation
`AgentRegistry`	interface	`Delegation`	lookup of registered agents	Delegation
`DelegationGrantStore`	interface	`Delegation`	persistence of consented delegations	Delegation
`TokenExchanger`	interface	`Delegation`	client side of RFC 8693 token exchange	Delegation
`TokenExchangeRequest`	`final readonly`	`Delegation`	RFC 8693 §2.1 request DTO	Delegation
`TokenExchangeResult`	`final readonly`	`Delegation`	RFC 8693 §2.2 response DTO	Delegation
`ActClaim`	`final` constants	`Delegation`	`act`, grant/token-type URNs, `pds_dgr`, `delegated+jwt`	Delegation
`DelegationContext`	`final readonly`	`Delegation`	cross-cutting observability context (sub+chain+grant)	Delegation
`DelegatedAuthorizationEngine`	interface	`Delegation`	intersection PDP (user ∩ agent), extends the engine	Delegation

Reading the reference

Each page documents, per symbol:

Contract — the exact PHP signature, copied from src/.
Why it exists — the problem it solves in the platform.
Who implements it — the concrete adapter(s), today and planned.
Who consumes it — the packages and code that depend on it.
Invariants / fail-closed defaults — the guarantees an implementation must keep.

Interfaces vs. value objects

Interfaces (AuthorizationEngine, KeyProvider, FeatureScope, …) are the ports you implement.
Value objects (SubjectRef, SessionMeta, the step-up DTOs) are immutable final readonly data you
construct and pass. Two enums (Aal, FeatureKey/ScopeLevel) carry tiny pure helpers but no behaviour to
couple to.