feat(auth): JWT verifiers, claim/header enums, and docs split

[ChiragAgg5k]

What

Adds a generic, dependency-free JWS verifier layer to utopia-php/auth (the mirror of the existing issuers), hardens it, modernizes the package, and splits the docs.

Verifiers (new)

• Verifier (base) — splits the compact JWS, base64url/JSON-decodes, enforces the alg-confusion guard, and validates standard claims. Concrete Verifiers\Asymmetric (RS256, public key) and Verifiers\Symmetric (HS256, shared secret) delegate only the signature check. Verifiers\VerificationException is thrown on any failure; verify() otherwise returns the decoded claims. Verifiers\Asymmetric::getKeyId() derives the kid the same way the issuer does.
• Immutable & coroutine-safe: configuration (issuer, audience, type, allowExpired, leeway) is passed via readonly constructor params with named args — no fluent setters that a shared instance could have flipped mid-verification:

  new Asymmetric($publicKey, issuer: $iss, audience: $aud, type: 'at+jwt', leeway: 30)

• Validation guarantees: exp is required and must be in the future; nbf/iat are always enforced when present; allowExpired: true relaxes only the expiry check (e.g. an OIDC id_token_hint). The typ header can be pinned to stop one token kind being accepted in place of another, and header/claims segments that decode to a JSON array (not an object) are rejected.
• Stays zero-dependency (native openssl/hash).

Enums (new)

• Enums\Claim (RFC 7519 registered claims + OAuth2/OIDC) and Enums\Header (RFC 7515 JOSE params), threaded through both the verifier and the issuers in place of scattered string literals.

Modernization

• readonly + constructor property promotion for set-once key material across the issuers and verifiers; Proof defaults its hash via a new initializer.
• Password now keeps its active hash aligned with its registry (a custom registry's algorithm is actually used, and removeHash's current-hash guard matches).
• Bumps the php constraint to >= 8.1 (enums + string-keyed array spread).

Tooling

• Enables phpstan (level 5) and rector for the package (matching sibling packages) and applies their fixes (package-wide declare(strict_types=1), final test classes, redundant-assertion cleanup, etc.).

Docs

• Splits the oversized README into a lean overview plus a docs/ folder (hashing, proofs, store, jwt); removes the dead Travis build badge.

Testing

• bin/monorepo check auth — pint + phpstan + rector all pass.
• bin/monorepo test auth — 156 tests, 380 assertions passing, including verifier round-trips and negative paths (tampered signature/claims, wrong key, expired/allowExpired, missing exp, future nbf/iat, iss/aud/typ/alg mismatch, non-object segments, malformed).

Notes

• Scope is the utopia-php/auth package only. A companion cloud-side refactor (consuming these verifiers, deduping the access-token issuer, dropping Ahc\Jwt) lives in a separate repo and depends on a tagged release of this package, so it ships separately.
• The wider Hash/Proof/Store classes keep their existing fluent setters (out of scope for this PR).

[greptile-apps]

Greptile Summary

This PR adds a JWT verifier layer (Verifier base + Verifiers\Asymmetric/Verifiers\Symmetric subclasses) that mirrors the existing issuer tree, introduces Enums\Claim and Enums\Header backed enums to replace scattered string literals across both issuers and verifiers, fixes the hash-registry alignment in Password, and splits the README into a docs/ folder.

• The verifier correctly guards against algorithm-confusion (alg check before signature), enforces exp presence by default, and keeps nbf/iat checks independent of allowExpired, with consistent clock-skew leeway across all time-based claims.
• The Enums migration threads through both the new verifiers and the existing issuers with no behavioral regressions; 148 tests (382 assertions) cover the full round-trip and negative paths.
• The PHP requirement bump to >=8.1 is appropriate given the use of backed enums and new expressions in constructor default values.

Confidence Score: 5/5

The new verifier layer is well-structured and the security-critical paths (alg guard, signature verification, claim enforcement) are all correct and covered by tests.

The algorithm-confusion guard, constant-time HMAC comparison, exp/nbf/iat leeway logic, and the immutable constructor design are all implemented correctly. The two findings are minor documentation and consistency nits that do not affect runtime behavior.

packages/auth/src/Auth/Verifiers/Asymmetric.php is missing declare(strict_types=1); packages/auth/src/Auth/Verifier.php has a misleading verify() docblock.

Important Files Changed

Filename	Overview
packages/auth/src/Auth/Verifier.php	New base verifier class; alg/type checks, claim validation, and leeway logic are correct, but the verify() docblock describes the execution order backwards (alg is checked before the signature, not after).
packages/auth/src/Auth/Verifiers/Asymmetric.php	New RS256 verifier; logic and key handling are sound, but the file is missing declare(strict_types=1) unlike its sibling Symmetric.php and the parent Verifier.php.
packages/auth/src/Auth/Verifiers/Symmetric.php	New HS256 verifier; uses hash_equals for constant-time comparison and correctly enforces the shared-secret requirement.
packages/auth/src/Auth/Enums/Claim.php	New backed enum for RFC 7519 / OAuth2 / OIDC claim names; covers all claims used by the issuers and verifiers.
packages/auth/src/Auth/Enums/Header.php	New backed enum for JOSE header parameters; complete and correct.
packages/auth/src/Auth/Issuers/Asymmetric/AccessToken.php	Migrated to Claim/Header enums; audience validation loop no longer checks that each element is a string (the is_string guard was removed in this PR).
packages/auth/src/Auth/Proofs/Password.php	Fixes hash-state alignment: the active hash is now taken from the registered registry (Argon2 if present, first entry otherwise) rather than always creating a new Argon2 instance.
packages/auth/tests/Auth/Verifiers/AsymmetricTest.php	New test suite covering round-trips, tampered signatures, wrong keys, alg mismatch, exp/nbf/iat enforcement, type checks, and non-object claims.
packages/auth/tests/Auth/Verifiers/SymmetricTest.php	New test suite for HS256 verifier covering happy path, wrong secret, expiry, audience mismatch, and leeway tolerance.

_{Reviews (4): Last reviewed commit: "(refactor): make the verifier immutable ..." | Re-trigger Greptile}