rodauth-ciba 0.1.0

data/docs/id-token-encryption.md

@@ -0,0 +1,288 @@
+# CIBA ID Token encryption
+
+> Latest policy supersedes the historical minimum-floor notes below: use explicit
+> HTTP freshness, and permit failed-fetch reuse only with publisher stale-if-error,
+> capped at60 seconds without renewing deadlines. See [operations](operations.md#remote-jwks-cache-lifetime).
+
+
+> Cache policy update: the user approved a minimum60-second successful JWKS
+> lifetime shared by CIBA authentication and encryption, without a new policy
+> switch. Earlier shorter-TTL comparisons below describe the previous runtime.
+> Failed-refresh reuse remains excluded; expiry followed by failed retrieval
+> does not renew freshness. See the current alignment closeout and Jev review.
+
+
+Enable recipient encryption explicitly:
+
+```ruby
+ciba_id_token_encryption_enabled true
+```
+
+For RSA encryption, register the client's public `jwks` or HTTPS `jwks_uri`. Select
+`id_token_encrypted_response_alg` plus `id_token_encrypted_response_enc`.
+Create storage columns for those two strings and the selected key metadata.
+Dynamic registration defaults omitted `enc` to `A128CBC-HS256` when `alg` is
+present; `enc` without `alg` is rejected. Discovery publishes enabled ID Token
+encryption algorithms without widening UserInfo/request-object encryption lists.
+The default flag is false. Configured encryption must never fall back to a signed
+plaintext ID Token; a failure rolls back issuance and leaves approval available.
+
+With the capability disabled, dynamic registration treats the two encryption
+fields as unsupported metadata: they are ignored, omitted from its response,
+and not stored. This follows the measured reference behavior. Clients must
+inspect returned registration metadata. This does not erase a statically
+configured encryption requirement or silently bypass one during issuance.
+
+The implementation supports RSA-OAEP and RSA-OAEP-256 recipient keys, plus
+client-secret-derived `dir`, A128KW/A192KW/A256KW and
+A128GCMKW/A192GCMKW/A256GCMKW, and ECDH-ES with optional AES-KW. These use A128GCM/A192GCM/A256GCM and A128CBC-HS256/A192CBC-HS384/A256CBC-HS512 content
+encryption. It first signs the ID Token, then encrypts it using `jwe`1.1.1
+and the CIBA-local GCMKW/ECDH adapters.
+RSA and Edwards ID Token signing both use this path, including refresh.
+The outer protected header carries cty=JWT, selected kid (if present), issuer
+and audience; no compression is enabled.
+
+For RSA algorithms, only registered client RSA keys of at least 2048 bits qualify. Optional alg must
+match; optional use must be enc. If key_ops is declared, selection requires
+encrypt and wrapping requires wrapKey. Both operations must be present to issue.
+A missing metadata-compatible recipient returns400 invalid_client_metadata;
+selected unusable key material or operation declarations fail processing. None
+of these failures falls back to an OP key. Existing JWKS retrieval controls
+apply. Do not supply a client's private key to the OP.
+
+When several keys qualify, keys explicitly matching alg and use have higher
+priority than keys omitting those fields. Equal scores preserve their input
+order, matching node-oidc-provider. Actual reference issuance and the gem's
+regression put a generic key first and verify that the explicitly tagged second
+key receives the encrypted token. [Before correction](validation/id-token-recipient-priority-red.txt),
+[three-DB regression](validation/id-token-recipient-priority-matrix.txt),
+[reference](validation/node-encrypted-id-tokens.txt).
+
+Encrypted ID Token *hints* remain unsupported, matching the measured reference
+behavior; clients can decrypt an issued ID Token before using its signed inner
+token as a hint. This is distinct from encrypted output support.
+
+Evidence: [Ruby regression](validation/id-token-recipient-encryption-current.txt),
+[three databases](validation/id-token-recipient-encryption-matrix.txt),
+[Node jose independent decryption](validation/id-token-recipient-encryption-jose.txt),
+and [reference OP](validation/node-encrypted-id-tokens.txt).
+The cross-library probe covers 36 algorithm combinations, initial issuance and
+refresh, inner signature verification and ciphertext tampering. Its temporary
+export includes an ephemeral synthetic recipient private key and must be removed
+after checking; it is not a committed fixture. Run the Ruby test
+`test_ciba_id_token_recipient_encryption` with `CIBA_ENCRYPTED_ID_TOKEN_EXPORT`
+set to a temporary path, then run `verify-gem-encrypted-id-tokens.mjs` with that
+path in the reference Node environment.
+
+This is an initial subset of node-oidc-provider encryption capabilities. ECDH,
+symmetric recipient encryption and all metadata-management/remote-key
+combinations remain outstanding.
+
+`examples/encrypted_id_token_smoke.rb` now runs from `bin/verify-package` after
+installing the built gem into a temporary directory. It exercises RS256,
+Ed25519 and EdDSA signatures with RSA-OAEP-256/A256GCM, opaque/JWT access tokens,
+initial issuance and refresh, recipient decryption and inner signature checks.
+It uses Rack requests and inline recipient keys; this does not establish remote
+HTTPS recipient retrieval. [Package evidence](validation/id-token-encryption-installed.txt).
+[Ruby 3.3/3.4 regression](validation/id-token-encryption-rubies.txt) covers the
+full suite on SQLite; two row-lock tests remain skipped on that database.
+
+## HTTPS recipient retrieval and failure atomicity
+
+The initial encryption path unintentionally used upstream's unguarded HTTP
+lookup during issuance. The [installed regression before correction](validation/id-token-encryption-https-red.txt)
+shows a forbidden loopback recipient being contacted and a token issued.
+The HTTP wrapper now covers CIBA issuance/refresh recipient retrieval as well
+as assertion/request keys. Upstream HTTP authorization failures during issuance
+raise an exception rather than halting with a response inside the transaction;
+this preserves source rollback.
+
+The [installed HTTPS probe](validation/id-token-encryption-https-installed.txt)
+runs with an explicitly trusted local certificate and a separate untrusted
+process. It verifies default loopback denial, explicit fixture-only allowance,
+TLS certificate rejection before the handler, GET without forwarded credentials,
+old-key cache retention, new-key use after explicit cache eviction, 503/malformed
+JSON failure rollback and subsequent recovery/refresh rotation in opaque and
+JWT access-token modes. Recipient decryption and the inner RSA signature are
+checked throughout. Real TTL passage is not measured; eviction is explicit.
+The private key never leaves the test recipient.
+
+[Database regressions](validation/id-token-encryption-remote-matrix.txt) also
+exercise redirects and oversized bodies during initial issuance and refresh.
+These use HTTP fixtures with an explicit loopback allowance; TLS evidence comes
+from the installed probe. The earlier supported-Ruby matrix predates this HTTP
+correction. Broader signing/encryption combinations and deployment conditions
+remain outstanding; remote-cache and management evidence follows below.
+
+After the HTTP correction, [full Ruby 4.0.6 regression](validation/id-token-encryption-https-full.txt)
+passes 348 tests /5,576 assertions on SQLite with two row-lock skips; the
+targeted three-DB matrix passes seven tests /802 assertions per database.
+
+## Reference remote cache and management comparison
+
+`test/reference/full-op/encryption-remote.mjs` exercises actual reference HTTP
+endpoints and key retrieval with a narrowly allowed local fixture URL. Live
+cache retains the old recipient; explicit expiry retrieves the replacement.
+Recipient decryption and inner signature/issuer/audience/subject are verified.
+No Authorization header reaches the key server.
+[Reference execution](validation/node-encryption-remote.txt).
+
+One concrete difference remains after failed recipient-key refresh. With 503
+and valid JSON, the reference first returns 400 invalid_client_metadata, then
+uses retained keys for the next token refresh without refetching while the key
+endpoint still fails. The gem rolls back and returns 500 server_error; fetch
+failures are not inserted as successful cache entries. Invalid JSON causes
+repeated refetch/failure in both implementations, with those different error
+codes; repairing the response restores issuance.
+
+The reference `ClientKeyStore.refresh` updates freshness before checking HTTP
+status, but parses JSON before updating freshness. This explains the observed
+difference. It also imposes at least 60 seconds of freshness; the gem's upstream
+HTTP cache honors no-cache without this floor. These probes force expiry rather
+than waiting for real TTL. Lifetime and post-failure key retention are unresolved
+alignment differences, not claimed equivalence or an approved new adaptation.
+No cache behavior was changed by this comparison.
+
+The reference also dynamically registers an encrypted client and updates its
+inline recipient via the management endpoint. Invalid encryption metadata leaves
+the old key intact; successful replacement changes the recipient for existing
+refresh credentials while the original token still decrypts with the old key.
+Gem tests `test_ciba_encryption_management_replaces_recipient_opaque` and
+`test_ciba_encryption_management_replaces_recipient_jwt` verify those boundaries
+in both access-token modes. [Database execution](validation/id-token-encryption-management-matrix.txt).
+This does not prove every management transition, remote URI change or concurrent
+registration update.
+
+### Defaults, removal and disabled registration
+
+The management probes now also omit enc while retaining alg: both implementations
+replace the previous A256GCM selection with A128CBC-HS256 and encrypt subsequent
+refresh responses accordingly. Removing both encryption fields clears the
+stored requirement and returns signed ID Tokens on existing refresh credentials.
+The tests follow rotated registration access tokens after each successful PUT;
+reusing the previous management token correctly fails authentication.
+
+Disabled-capability registration originally stored and returned the encryption
+fields, although issuance could not honor them. An initial proposal to reject
+registration was revised after the reference returned 201 while omitting both
+fields. The implementation now ignores them, matching the reference's response
+and stored client. [Reference registration](validation/node-encryption-disabled-registration.txt),
+[reference updates](validation/node-encryption-remote.txt),
+[final DB matrix](validation/id-token-encryption-config-matrix.txt).
+This correction is confined to CIBA registration; ordinary OAuth clients follow
+their existing upstream handling.
+
+## Client-secret-derived encryption
+
+`dir`, AES-KW and AES-GCMKW do not require recipient JWKS. The OP derives
+bytes from the UTF-8 client secret using SHA-256 for lengths up to32 bytes,
+SHA-384 up to48, and SHA-512 up to64, truncating to the required length. AES-KW
+uses the wrapping-key size; `dir` uses the content-encryption key size (the
+full combined MAC/encryption size for CBC-HS). This follows the pinned
+node-oidc-provider9.12.2 client model and its actual issuance/refresh output.
+It is distinct from HMAC signing, which uses the original secret directly.
+
+`ciba_id_token_encryption_secret(oauth_application:)` retrieves the original
+secret and by default delegates to `ciba_id_token_hmac_secret`. Verified
+Basic/POST credentials can be reused within that authenticated request even
+with hash storage. Explicit plaintext storage is the fallback. Applications
+using private-key authentication with hashed secrets must supply an original
+secret through the callback. A missing, empty or invalid-encoding secret fails
+issuance and rolls back consumption; the hash is never used as the secret.
+
+The [reference probe](validation/node-encryption-symmetric.txt) verifies42
+combinations, including AES-GCMKW, without recipient JWKS. The initial symmetric increment
+implemented24 combinations (`dir`/AES-KW × six content methods); the
+[local tests](validation/symmetric-encryption-current.txt) verify hashed-secret
+DCR, initial/refresh issuance, wrong keys and missing-secret rollback.
+[Independent jose verification](validation/symmetric-encryption-jose.txt)
+decrypts48 actual gem tokens and verifies their inner RS256 signatures.
+The standalone verifier takes a disposable vector file exported with
+`CIBA_SYMMETRIC_EXPORT`; synthetic secrets must not be committed.
+
+ECDH is now implemented by the CIBA-local adapter described below. The `jwe`1.1.1 `VALID_ALG` list
+names ECDH and AES-GCMKW, but its algorithm dispatcher has no implementations.
+AES-GCMKW is now provided by the CIBA-local adapter described below; ECDH is
+handled separately. Broader authentication/signature combinations remain pending. Existing RSA evidence does not establish those cases.
+
+The [three-DB encryption subset](validation/symmetric-encryption-matrix.txt)
+passes10 tests/1,211 assertions on each SQLite/PostgreSQL/MySQL. A subsequent source-review
+found that upstream `oidc.rb#generate_id_token` eagerly calls
+`oauth_application_jwks` before encoding. The [regression reproduction](validation/symmetric-jwks-red.txt)
+confirmed that an unrelated503 JWKS URI incorrectly prevented symmetric issuance.
+A CIBA-only generation scope now skips that recipient lookup for symmetric
+algorithms and restores the previous scope on success or exception. Authentication
+outside generation still resolves and validates the registered public key.
+The [targeted HTTP tests](validation/symmetric-jwks-current.txt) verify zero
+recipient requests during Basic issuance/refresh and actual private_key_jwt
+retrieval with wrong-key rejection and recovery. The [reference probe](validation/node-symmetric-jwks.txt)
+verifies84 combinations (42 without JWKS and42 with a503 URI), all without
+recipient retrieval. This does not suppress asymmetric encryption or ordinary OP
+key retrieval.
+
+The [full local regression](validation/symmetric-encryption-full.txt) passes356 tests/6,261 assertions, with two SQLite row-lock skips.
+
+The updated [three-DB subset](validation/symmetric-jwks-matrix.txt) passes21
+tests/1,505 assertions per DB, including encryption and client assertions.
+The [installed artifact](validation/symmetric-encryption-installed.txt) passes16
+symmetric cases across four key algorithms, Basic with hashed storage / POST
+with plaintext storage, and opaque/JWT access tokens. It decrypts and verifies
+initial and refresh ID Tokens while an unrelated JWKS URI is configured and
+any outbound recipient HTTP call would fail the smoke. Existing RSA and TLS
+package checks also pass. The build reuses installed dependencies; network
+resolution of dependencies is not established.
+
+[Supported Ruby regression](validation/symmetric-encryption-rubies.txt) passes358 tests/6,274 assertions on each Ruby3.3 and3.4, with two SQLite row-lock skips.
+
+## AES-GCM key wrapping
+
+The CIBA-local adapter supports A128GCMKW/A192GCMKW/A256GCMKW. It uses OpenSSL
+AES-GCM to wrap a newly generated content key, with a fresh12-byte random IV,
+empty wrapping AAD and a16-byte authentication tag. Both wrapping parameters
+are included in the protected header, which the JWE backend authenticates as
+content AAD. Content encryption and compact serialization remain in `jwe`;
+there is no global algorithm registration or new token-decryption endpoint.
+The client-secret derivation above also applies to GCMKW.
+[RFC7518 §4.7](https://www.rfc-editor.org/rfc/rfc7518.html#section-4.7).
+
+The [registration red test](validation/gcmkw-red.txt) failed before the adapter.
+The expanded [local symmetric tests](validation/gcmkw-current.txt) pass42
+algorithm/content combinations, checking DCR with hashed storage, initial and
+refresh output, wrapping IV/tag lengths and distinct sampled IVs. This sampling
+is not a guarantee of collision-free operation; randomness comes from
+`SecureRandom` for each wrap and from the JWE backend for content keys/IVs.
+The [independent jose verifier](validation/gcmkw-jose.txt) decrypts84 actual gem
+tokens, verifies the inner RS256 signature, rejects wrong keys, and rejects
+changes to wrapping IV/tag, encrypted key, ciphertext and content tag.
+
+The [reference execution](validation/node-symmetric-jwks.txt) already covers
+all42 combinations with and without an unrelated503 JWKS URI. The updated [installed-artifact smoke](validation/gcmkw-installed.txt) covers
+all seven symmetric key algorithms in28 configurations: hashed Basic/plaintext
+POST and opaque/JWT access tokens. Initial and refresh tokens are unwrapped,
+decrypted and signature-checked, with unexpected recipient HTTP calls rejected.
+Supported-Ruby validation is recorded separately below.
+
+The [GCMKW encryption regression subset](validation/gcmkw-matrix.txt) passes17 tests/1,794 assertions on each SQLite/PostgreSQL/MySQL. The [full local regression](validation/gcmkw-full.txt) passes358 tests/6,724 assertions with two SQLite row-lock skips.
+
+The [GCMKW supported-Ruby regression](validation/gcmkw-rubies.txt) passes358 tests/6,724 assertions on each Ruby3.3 and3.4, with two SQLite row-lock skips. The [ECDH contract](research/ecdh-encryption-reference-contract.md) records96 reference configurations and the new adapter with its remaining validation gates.
+
+## ECDH recipient keys
+
+ECDH-ES and ECDH-ES+A128KW/A192KW/A256KW accept registered public P-256,
+P-384, P-521 or X25519 recipient keys. All six content methods above are
+supported. Public JWKS/jwks_uri is required; client-secret retrieval is not used.
+For ECDH public recipients, `key_ops` must be omitted or empty, matching the
+reference's public-key import behavior. Nonempty declarations fail issuance; see
+the [metadata comparison](research/ecdh-encryption-reference-contract.md#recipient-key-metadata).
+The protected header includes a fresh public epk, recipient kid when present,
+cty/issuer/audience. Direct ECDH has an empty encrypted-key segment; wrapping
+variants use the existing AES-KW backend. Unsupported curves and invalid key
+agreement fail instead of returning plaintext. See the [reference and current
+validation contract](research/ecdh-encryption-reference-contract.md).
+
+This is an initial implementation. [Installed-artifact validation](validation/ecdh-installed.txt)
+now covers32 ECDH configurations. [Ruby3.3/3.4](validation/ecdh-rubies.txt) each pass361 tests/9,074 assertions.
+ECDH-specific HTTP/HTTPS key retrieval, failure/rotation and sequential management
+now pass ([contract](research/ecdh-encryption-reference-contract.md#gem-remote-retrieval-and-management)); real TTL is now [measured](research/ecdh-encryption-reference-contract.md#actual-cache-expiry-without-mutation), with a shorter-max-age policy difference; [management/issuance overlap](research/ecdh-encryption-reference-contract.md#management-update-overlapping-issuance) now has reference and three-DB snapshot evidence.
+
+Recipient selection follows explicit alg/use priority and stable input order. Cryptographic validation occurs after selecting the recipient: an unusable preferred key fails issuance without trying another key. [Comparison and regression evidence](research/ecdh-encryption-reference-contract.md#multiple-recipients-and-invalid-preferred-keys).

data/docs/id-token-hint.md

@@ -0,0 +1,174 @@
+# Optional ID Token hints
+
+Enable `ciba_id_token_hint_enabled true` and implement
+`resolve_ciba_id_token_subject(subject, oauth_application:)`. The callback receives
+a cryptographically verified subject (public or enabled pairwise) and the authenticated client record;
+return the corresponding local account ID or nil. Do not assume custom public
+subjects are database primary keys. Normal account eligibility and subsequent
+approval/account/client binding checks still apply. No migration is needed.
+
+Exactly one of `login_hint`, enabled `login_hint_token`, or enabled `id_token_hint`
+is accepted. ID Token hints are limited to 8192 bytes. Raw hints are removed before
+request persistence, transaction hooks, device snapshots and observation events.
+Applications must separately redact incoming HTTP parameters in their own logs.
+
+The dedicated hint verifier uses the authenticated client's configured ID Token
+signing algorithm, falling back to the OP's first signing algorithm as the issuer
+does. It checks signature, issuer, audience membership and a string subject.
+Like the reference hint verifier, it ignores expiration and does not require iat
+or exp. If present, iat/nbf must be numeric; fractional values are accepted. Future
+nbf is rejected with the configured leeway. Future iat is rejected only when exp
+is absent. A present jti must be a string. Supported algorithm families
+are RS, PS, ES and HS; all twelve256/384/512 variants have actual issuance,
+current/expired reuse and wrong-key rejection tests.
+Unsigned and encrypted hints are not supported. A valid nested encrypted hint
+is rejected before subject resolution, matching the measured node-oidc-provider
+9.12.2 CIBA behavior even with its encryption feature and OP key configured.
+
+Asymmetric keys come from `oauth_jwt_public_keys[algorithm]`, falling back to
+`oauth_jwt_keys[algorithm]` only when no public-key entry exists. Arrays retain
+old verification keys. A supplied kid must match the trusted key's JWT::JWK kid;
+without kid all configured keys for the pinned algorithm may be tried. No token
+URL or embedded key is fetched or trusted. Removing a key stops acceptance of
+hints signed by it. CIBA HMAC issuance and hint verification use the authenticated
+client's secret, matching the reference. See the secret retrieval contract below.
+
+Expiration is ignored **only in this dedicated hint verifier**. By default
+`ciba_id_token_hint_max_age nil` leaves age unrestricted while keys remain
+trusted, matching the measured node behavior. Set a positive integer number of
+seconds to limit age from iat. This is separate from expiration and does not
+alter normal access-token or client-assertion validation.
+
+The hint path now matches the measured reference's azp and typ handling: neither
+is used to reject a hint. Registered algorithm, trusted key, issuer and client
+audience remain mandatory. The recognized JOSE critical declaration b64=true
+is accepted; unknown critical extensions and unencoded JWT payloads are rejected.
+This change is isolated to hints; access-token, signed-request and client-assertion
+validation is unchanged. With an explicit ciba_id_token_hint_max_age, iat is
+required to evaluate that application age policy. Optional [pairwise subjects](pairwise.md)
+use the same resolver boundary to map the verified subject to a canonical account.
+
+The reference even ignores the type of exp in this identity-hint path. This is
+not a contract for issuing malformed ID Tokens or accepting them as authentication
+results. The regression re-signs controlled variants and proves they still only
+create pending requests. [Reference](validation/node-id-hint-validation-profile.txt),
+[three-DB regression](validation/id-hint-validation-matrix.txt).
+
+Successful hint validation creates a pending request, not an approval or token.
+New customer authentication/approval remains mandatory. See the
+[reference measurements](research/id-token-hint-reference-contract.md) and
+[local tests](validation/id-token-hint-tests.txt). The later
+[encrypted-hint boundary test](validation/encrypted-hint-boundary.txt) and
+pairwise integration tests extend that evidence. Edwards ID Token support is explicitly configured as described below; arbitrary
+application resolver correctness remains outside the verified scope.
+
+## Complete configured RS/PS/ES/HS matrix
+
+The updated test verifies each actually issued ID Token using its configured
+key, issuer and audience, then tests current and expired reuse as hints. Neither
+form inherits approval; a token signed by a different key is rejected before
+request persistence. The HMAC client-secret negative case explicitly selects
+HS256 first, so it tests wrong key ownership rather than only algorithm mismatch.
+[Three databases](validation/id-hint-algorithms-matrix.txt): seven tests /229
+assertions per DB, no failures/errors/skips.
+
+The independent reference matrix now covers those twelve plus Ed25519/EdDSA
+([execution](validation/node-id-hint-algorithms.txt)). Edwards issuance/hint verification was a concrete remaining gap; the initial
+implementation below addresses it separately from request-object/client-assertion verification.
+
+## Explicit Edwards ID Token keys
+
+Configure `ciba_id_token_signing_keys` with `"Ed25519"` and/or `"EdDSA"` entries
+containing an OpenSSL Ed25519 private key. Default is an empty hash. The client
+must explicitly select the matching `id_token_signed_response_alg`; the ordinary
+OP default signing algorithm is unchanged. Each entry may instead be an array:
+the first key signs new ID Tokens, and later public/private keys are retained
+for hint verification. The first key must be private and all keys must be Ed25519.
+
+The shared JWKS publishes only public OKP material with RFC7638-derived kid, alg
+and sig use; existing upstream keys remain present. Discovery adds the configured
+ID Token algorithms. CIBA issuance signs with the selected key, and hints verify
+with the same configured/retained public keys. Removing a retained key prevents
+acceptance of its hints. Hint issuer/audience/subject/time checks and new-approval
+requirements remain in force. This does not change JWT access-token signing.
+
+The gem continues to include at_hash, using the left half of SHA-512 for Edwards.
+The reference's CIBA token-endpoint default omits this optional claim; its
+ID Token model maps both Edwards algorithm names to SHA-512 when hashing is
+requested. This is not a claim that their default claim sets are identical.
+
+Edwards ID Tokens can use the optional [recipient encryption](id-token-encryption.md)
+path. Without that enabled capability, an encryption selection raises
+ConfigurationError instead of emitting plaintext and keeps approval available.
+Independent Node verification, installed artifact and supported-Ruby evidence for
+signed output is recorded in the [contract](research/id-token-hint-reference-contract.md).
+Encryption has its own narrower evidence and remaining integration work.
+[Initial14-test three-DB regression](validation/edwards-id-token-matrix.txt),
+[final Edwards/rollback cases](validation/edwards-id-token-final-matrix.txt).
+
+## HMAC client-secret ownership
+
+CIBA ID Tokens signed with HS256/HS384/HS512 now use the UTF-8 client secret for
+both issuance and hint verification, as required by
+[OIDC Core ID Token validation](https://openid.net/specs/openid-connect-core-1_0.html#IDTokenValidation).
+The algorithm is still selected by registered `id_token_signed_response_alg`
+or the upstream default, and must be configured among the supported signing
+algorithms. OP-wide HS keys are not a fallback for a missing client secret.
+Non-CIBA JWT encoding and JWT access-token signing retain upstream key handling.
+
+After successful client_secret_basic/client_secret_post authentication, the
+verified secret is retained only on that request's Rodauth instance, bound to
+the authenticated application's ID. This works with hashed DB storage; no new
+plaintext persistence is introduced. With explicitly configured plaintext
+client-secret storage, other authentication methods can use the stored secret.
+For hashed storage plus private_key_jwt/mTLS, supply an application secret lookup:
+
+```ruby
+ciba_id_token_hmac_secret do |oauth_application:|
+  secrets.fetch(oauth_application.fetch(:client_id)) # application's secret store
+end
+```
+
+The callback must return that client's original secret, not its password hash
+or an OP signing key. Missing/non-string secrets and insufficient key length
+fail issuance with rollback; they do not produce an ID Token with another key.
+Minimum byte lengths are 32/48/64 respectively, following
+[JWA section 3.2](https://www.rfc-editor.org/rfc/rfc7518.html#section-3.2);
+secret entropy and secure storage remain application responsibilities.
+Current-secret rotation changes both new issuance and accepted HMAC hints.
+
+This replaces the unreleased implementation's OP-key HMAC behavior. Previously
+issued OP-key HMAC hints are no longer accepted unless that key is actually the
+client secret. Do not configure a shared OP key as every client's secret to
+preserve those tokens.
+
+[Three-DB tests](validation/hmac-id-token-matrix.txt) cover Basic/POST,
+plaintext/hashed storage, all three HS algorithms, initial issuance/refresh,
+current/expired hints, wrong OP key rejection and missing/short callback rollback.
+[Full local regression](validation/hmac-id-token-full.txt) passed353 tests before
+the additional registration-length case below.
+
+The installed [HMAC smoke](../examples/hmac_id_token_smoke.rb) exercises all
+three algorithms with plaintext/hashed secret storage and opaque/JWT access
+tokens. It verifies initial issuance, refresh, hints and rejection of the OP key.
+Replacing the stored client secret rejects old authentication and old HMAC hints;
+existing refresh credentials issue with the new secret after new authentication.
+This is a backend replacement fixture, not a standard secret-rotation endpoint
+or a measurement of reference cache propagation.
+[Installed artifact evidence](validation/hmac-id-token-installed.txt),
+[Ruby 3.3/3.4 evidence](validation/hmac-id-token-rubies.txt).
+
+### Dynamically generated secret length
+
+Upstream's default generated secret is43 encoded bytes, insufficient for HS384
+and HS512 signing. A [regression](validation/hmac-registration-secret-red.txt)
+reproduced the HS384 failure. For CIBA registration only, the gem now replaces
+an insufficient generated secret with fresh cryptographic randomness sized for
+the selected algorithm, using the upstream secret setter to preserve configured
+hash storage. HS256 and unrelated clients keep their existing generation path.
+This applies whether or not management-token issuance is enabled.
+[Three-DB regression](validation/hmac-registration-secret-matrix.txt) verifies
+registration, hashed storage, authenticated CIBA issuance and client-secret
+signature validation for all three algorithms. The
+[reference registration fixture](validation/node-hmac-registration-secret.txt)
+also produces secrets meeting the algorithm's minimum length.

data/docs/login-hint-token.md

@@ -0,0 +1,35 @@
+# Optional login_hint_token
+
+The default profile continues to accept `login_hint`. Enable `login_hint_token` explicitly and supply an application resolver in the same configuration block:
+
+```ruby
+ciba_login_hint_token_enabled true
+resolve_ciba_login_hint_token do |token, oauth_application:|
+  # Your service validates the token and returns its local account ID or nil.
+  HintService.resolve(token, client_id: oauth_application[:client_id])
+end
+```
+
+`HintService` is an application example, not a class supplied by the gem. The resolver is required at configuration time when enabled. It receives the already-authenticated OAuth client. Like node-oidc-provider's `processLoginHintToken`, this API does not mandate a token format. It can accept an opaque reference or an application-defined signed token. The application owns authenticity, permitted issuer/audience/client, expiry, replay rules where needed and mapping to the OP's local account. For JWT formats, use appropriate signature/claim validation with trusted keys; decoding alone is not identity verification.
+
+The Backchannel Authentication Endpoint requires exactly one supplied `login_hint`, enabled `login_hint_token`, or enabled `id_token_hint`. Empty, non-string, multiple or oversized hints return invalid_request. The token limit is 8,192 bytes, also bounded by the total form-body limit; ordinary login_hint remains limited to 1,024 bytes. This capability adds no custom Discovery field and needs no DB migration.
+
+Return nil for a token that does not identify an eligible local account; the response is unknown_user_id. The gem also checks the resulting account is active. Resolver exceptions use the existing server-error boundary and do not create a request. Configuration does not replace the existing `resolve_ciba_login_hint`, which remains required for the default mechanism.
+
+For an expired token, raise `Rodauth::CibaSupport::ProtocolError,
+"expired_login_hint_token"` to return the corresponding HTTP400 response.
+Other unexpected resolver failures produce HTTP500 rather than claiming that
+the customer is unknown. The application must document accepted token formats,
+issuers and age policy for its clients. Signature policy, single-use references
+and discovery-service encrypted tokens are application implementations, not
+built-in token formats provided by this gem.
+
+After successful resolution, only the account binding enters the stored request. The raw token is removed before request hooks, persistence, device callbacks and observation events. The incoming Rack request necessarily still contains the submitted parameter; application/request logging must apply its own filtering. The reference OP retains raw hint parameters in its asynchronous request; discarding the value is this gem's deliberate storage adaptation.
+
+Approval and saved-consent account/client checks remain unchanged. Token-endpoint parameters cannot re-resolve or replace the subject. Disabling this hint mechanism prevents new hint-token requests but does not invalidate already-resolved pending requests: those continue using their saved identity and ordinary completion/expiry/revocation checks.
+
+## Evidence and scope
+
+`test/ciba_hint_token_test.rb` verifies opt-in/resolver requirements, invalid shapes/size, mixed hints, client-aware resolver behavior, active-account and approval identity checks, raw-token exclusion from DB/snapshots/events, poll tampering and completion after deactivation. The complete node HTTP harness checks an application-defined opaque hint, client policy, mixed hints, unknown user and the signed ID Token subject. The installed-gem extension smoke now uses this mechanism with claims/resource/RAR.
+
+These tests validate the protocol-to-application boundary, not an arbitrary production token format. The fixture resolver recognizes fixed local test references; it is not a reusable production verifier. [Signed authentication requests](signed-requests.md) and [ID Token hints](id-token-hint.md) have separate opt-in implementations and evidence.

data/docs/max-age.md

@@ -0,0 +1,65 @@
+# CIBA maximum authentication age
+
+The gem accepts `max_age` at the backchannel endpoint as a node-oidc-provider
+extension. This does not add a CIBA Core conformance requirement.
+
+An explicit request value overrides client `default_max_age`. Omission or an empty
+string uses the registered default, if any. Signed requests use only their signed
+max_age; an unsigned outer value cannot override or supply it.
+
+The accepted maximum age is saved with the request before device dispatch. The
+application receives it through `trigger_ciba_authentication_device` and can read
+it later using `ciba_request`:
+
+- `nil`: no maximum age was selected.
+- `0`: require fresh authentication.
+- A positive integer: maximum authentication age in seconds.
+
+Node retains positive inputs as strings in request.params; zero becomes its
+internal `prompt=login`. The Ruby API uses an integer, retaining zero explicitly,
+so applications need no second prompt field to distinguish fresh authentication
+from no policy. This is an internal representation adaptation, not an HTTP response
+change. Client metadata changes after acceptance do not alter the saved policy.
+Applications must enforce freshness during authentication; approval does not reject
+an old supplied auth_time automatically. Selected max_age causes auth_time to be
+selected for ID Token output, but does not invent an authentication time.
+Refresh preserves the original authentication claim selection/context and does
+not start a new authentication request or reapply current client defaults.
+
+## Parsing and migration
+
+Validation follows the measured Node numeric boundary: a finite, non-negative
+safe integer (at most9007199254740991) after numeric conversion. Integral decimal
+and exponent representations and unsigned hexadecimal/binary/octal representations
+are accepted. Whitespace-only input and negative zero mean zero. Unsupported
+syntax, fractional results, negative numbers, nonfinite numbers and arrays are
+rejected before saving or dispatching. The gem bounds the input to1024 UTF-8 bytes.
+
+New request tables include nullable BIGINT `max_age`. Existing development schemas
+must add it explicitly before upgraded workers start:
+
+```ruby
+Rodauth::CibaSupport::Schema.add_request_max_age(db)
+```
+
+Pass `table:` / `column:` and configure `ciba_request_columns[:max_age]` for custom
+storage. Startup requires this column. Existing requests remain NULL; migration
+does not reinterpret them using today's client defaults. This migration is in
+addition to the [authentication_claims migration](authentication-claims.md).
+No refresh-table max_age column is needed.
+
+## Evidence
+
+The [pinned reference test](../test/reference/full-op/max-age.mjs) checks request
+overrides, numeric forms, zero-to-login conversion, invalid values and successful
+signed ID Tokens using an application-supplied old authTime. See its
+[execution](validation/node-max-age.txt). Gem tests cover saved/frozen callback
+policy, later metadata changes, signed input isolation, rejected values, custom
+columns and forward migration. No deployment authentication policy is verified.
+
+Validation: [Ruby3.3 / SQLite full suite](validation/max-age-ruby33.txt) passes391
+tests /10,418 assertions with two row-lock skips. The [Ruby3.4 three-DB subset](validation/max-age-matrix.txt)
+passes22 tests /1,317 assertions on each of SQLite/PostgreSQL/MySQL. Containers
+reuse existing dependency images and mount current source read-only.
+The [installed artifact smoke](validation/max-age-installed.txt) also passes;
+it reuses locally installed dependencies rather than testing network resolution.