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"]

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

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.