rodauth-ciba 0.1.0

data/docs/outbound-http.md

@@ -0,0 +1,52 @@
+# CIBA outbound HTTP boundary
+
+Signed CIBA request JWKS fetching and protected CIBA-client assertion JWKS
+fetching use a dedicated transport boundary while retaining upstream's
+registered-key lookup and cache. Unrelated OAuth clients keep their existing
+HTTP behavior. Optional ping uses the same boundary with its own
+HTTPS endpoint validation.
+
+The default `ciba_http_address_allowed?(address)` rejects special-use address
+ranges, including private/loopback/link-local addresses, multicast and mapped
+IPv4 equivalents. IPAddr parses addresses; text prefixes are not trusted.
+Every DNS answer must pass policy. The connection is pinned to the first
+validated address via Net::HTTP#ipaddr while retaining the original hostname
+for Host and TLS verification. Ambient HTTP proxies are disabled so they cannot
+bypass that destination check. The shared request primitive does not follow
+redirects. Sector-document fetching explicitly follows up to 20 redirects,
+repeating the same destination checks at every hop under one 2.5-second deadline.
+Ping and JWKS fetching retain their existing refusal to follow redirects.
+
+For JWKS and sector documents the transport bounds response bodies to 65536 bytes.
+Ping needs only the response status: it closes the connection immediately after
+headers without reading or draining the body. The transport uses a 2.5-second outer
+Ruby timeout, as well as connection/read/write timeouts. Registered JWKS URIs
+retain upstream's HTTP/HTTPS scheme support; production registrations should
+use HTTPS. Userinfo, fragments and other URI schemes are rejected. Transport
+validation failures are invalid_request for signed CIBA authentication requests
+and invalid_client for JWT client authentication. They do not save pending work.
+
+If an application deliberately needs an internal endpoint, override
+`ciba_http_address_allowed?` narrowly for that deployment. Returning true allows
+that resolved address. There is no default private-network exception. The
+loopback JWKS fixture overrides only 127.0.0.1 on its test app; this is not a
+production recommendation. Operators must account for the separate risk of
+which clients may register destinations, and retain their egress controls.
+
+Compared with node's connected-socket guard, the gem validates all DNS answers
+and pins one before connection. It additionally rejects multicast and
+IPv4-compatible IPv6. It does not implement multi-address connection fallback.
+The allow-policy applies when a network lookup happens; an already cached JWKS
+remains usable until upstream cache invalidation/expiry. Network refusal alone
+is therefore not a key-revocation mechanism.
+
+Tests cover IP ranges/mapped forms, default loopback refusal before any receiver
+request, mixed DNS answers, hostname/TLS configuration and IP pinning, real
+loopback cache/rotation/error behavior under a narrow test exception, and an
+oversized response. The DNS pinning test inspects the configured Net::HTTP
+client; it is not an adversarial live DNS-rebinding experiment. Installed-gem
+ping tests directly verify untrusted TLS rejection and a stalled receiver's
+timeout; saved approval survives. Hostname mismatch and expired certificates
+remain unverified.
+The independent node ping harness separately verifies real TLS notifications
+and default loopback rejection; do not transfer that evidence to the gem.

data/docs/pairwise.md

@@ -0,0 +1,76 @@
+# Optional pairwise CIBA subjects (integration in progress)
+
+Pairwise is off by default. First run the explicit migration
+`Rodauth::CibaSupport::Schema.add_pairwise_subject(db)` to add nullable
+`oauth_grants.ciba_subject` (custom table/column supported; configure
+`ciba_token_subject_column` for a renamed column). Enable `ciba_pairwise_enabled true` only together
+with `ciba_pairwise_identifier(account_id, oauth_application:, sector_identifier:)`.
+The callback must return a stable, nonempty ASCII subject of at most 255 bytes.
+The application owns its secret/persistence lifecycle and sector/account mapping;
+the gem does not supply a default hash or a reversible identifier store.
+
+This integration supports private_key_jwt and self_signed_tls_client_auth clients
+with registered jwks_uri, and no simultaneous inline jwks. Enable upstream
+`:oauth_jwt_bearer_grant` and create its CIBA replay ledger with
+`Schema.create_client_assertions(db)` if not already migrated. The standard client columns jwks_uri,
+sector_identifier_uri, response_types and redirect_uri must be available where
+used. Existing public clients retain their behavior. Self-signed TLS clients
+require upstream `oauth_tls_client_auth` plus the explicit trusted certificate
+callback described in the [mTLS contract](research/mtls-reference-contract.md).
+The peer certificate must match x5c from the registered jwks_uri; PKI TLS
+authentication alone is not a proof of that key ownership. Signed-request-only
+proof with another client authentication method is rejected, matching the pinned
+node-oidc-provider registration policy even when signed requests are enabled.
+This is a shared policy restriction, not a remaining reference-alignment gap.
+
+For CIBA-only clients with no browser response_types, absent sector_identifier_uri
+means the sector is jwks_uri's host including a nondefault port. An explicit
+sector_identifier_uri must be HTTPS. Browser response_types require that explicit
+URI. Its HTTP 200 JSON array must include jwks_uri and, for browser clients, all
+redirect_uris. Fetching uses the bounded address-checked outbound transport;
+successful validation is cached per Rodauth application class using a digest of
+the complete client row, with a 100-entry LRU bound and no time-based expiry.
+Static and dynamically stored clients validate on a cache miss. Registration
+and management replacement always fetch afresh, even for unchanged metadata.
+Failures are not cached; an unsuccessful replacement does not erase the old
+client's valid cache entry. Network I/O occurs outside the cache mutex, so
+concurrent cold lookups may fetch twice. Processes do not share the cache.
+This does not yet implement node's configurable sector-validation bypass policy.
+
+Only the emitted subject is pairwise: saved requests, consent and OAuth grants
+retain the canonical account ID. UserInfo must return the same pairwise subject
+as ID Token. With pairwise enabled, new CIBA issuances snapshot their subject in that token
+row. JWT UserInfo checks the signed subject against this snapshot and the bound
+client before using the internal account for lookup. After a management sector
+change, old tokens can therefore authenticate while UserInfo emits the new
+sector subject, as measured with node opaque tokens. Refresh also uses the new
+sector, and already-issued JWT bytes remain unchanged. Older rows with no
+snapshot retain the prior current-subject check; a sector change can invalidate
+those old JWTs. The migration does not invent historical subjects.
+
+For id_token_hint, configure the existing `resolve_ciba_id_token_subject` callback
+to recover the canonical account in the authenticated client's context. The gem
+first verifies the ID Token's issuer, audience and signature; the hint then starts
+a new request requiring approval. Do not treat a hashed subject as a new account.
+
+Current tests cover opaque/JWT access tokens with verified ID Token, UserInfo,
+app-resolved ID hint, internal identity, same/different sector derivation,
+dynamic registration constraints and stubbed sector document membership. Opaque/JWT refresh also verifies subject and internal-account preservation,
+rotation/replay, wrong-client refusal, and rollback on invalid identifier results.
+Installed-gem tests now fetch sector documents over verified HTTPS and reject
+untrusted certificates, invalid membership/JSON, oversize and HTTP errors without
+persistence or forwarding the registration bearer. Sector fetching now follows 301/302/303/307/308 (up to 20 redirects), validating
+each destination with the outbound policy and limiting the entire chain to
+2.5 seconds. The measured same-origin HTTPS 302 case agrees with node. Existing-token UserInfo and refresh after a management sector change are now
+verified for opaque/JWT tokens. Pending requests retain their canonical account and unapproved state across a
+sector update; subsequent approved issuance uses the new sector subject. The
+installed-gem TLS fixture now covers hybrid DCR, real remote-key authentication,
+approval, verified ID Token, saved subject and matching UserInfo. Concurrent
+sector management/issuance tests now verify one issuance subject across storage
+and tokens, followed by current-sector UserInfo, on all three DBs. PostgreSQL and
+MySQL force the update to commit while issuance is paused; SQLite tests writer
+contention and either serial order. Concurrent refresh/key changes, arbitrary
+application hooks and additional deployment combinations remain unverified.
+This is not a completed pairwise parity or release-readiness claim.
+
+[Reference contract](research/pairwise-reference-contract.md).

data/docs/ping.md

@@ -0,0 +1,118 @@
+# Optional ping delivery
+
+Run the explicit migration and enable the capability:
+
+```ruby
+Rodauth::CibaSupport::Schema.add_ping(db)
+# Rodauth configuration:
+ciba_ping_enabled true
+```
+
+Register each ping client with backchannel_token_delivery_mode = ping and an
+HTTPS backchannel_client_notification_endpoint. Poll clients remain supported.
+Discovery advertises poll/ping only while enabled. The migration adds the client
+endpoint column and a separate ciba_ping_deliveries table, leaving existing
+requests and grants intact. Custom migration keywords: applications_table,
+endpoint_column, table, requests_table, request_key. Configure the corresponding
+Rodauth endpoint-column and ciba_ping_deliveries_table settings when renamed.
+
+The initiation request must provide a nonempty client_notification_token using
+Bearer token characters, at most 1024 bytes. Entropy is the client's responsibility.
+Clients must generate at least128 bits of entropy (160 is recommended). The gem
+validates syntax/length, not the randomness of a supplied token. The application
+should verify that the registered notification endpoint is controlled by the
+client; HTTPS validation and destination filtering alone do not prove ownership.
+The receiving client must check the notification bearer and its association
+with auth_req_id before collecting tokens. An OP-side send test does not prove
+that receiver behavior. See [CIBA Core §§7.1,10.2,14](https://openid.net/specs/openid-client-initiated-backchannel-authentication-core-1_0.html).
+Poll ignores this parameter. Signed requests use only its signed inner value.
+Invalid metadata, userinfo/fragments or non-HTTPS endpoints cannot enable a ping
+client. Network destination checks apply at send time using the
+[CIBA HTTP boundary](outbound-http.md), which rejects special-use destinations
+by default. There are no redirects, ambient proxies or automatic retries.
+
+## Persistence and API behavior
+
+The private delivery table stores request_id, original auth_req_id, the
+notification token and the registered endpoint at acceptance. The endpoint column
+is retained as acceptance-time data for schema compatibility; dispatch uses the
+current client registration, not that saved endpoint. Unlike the
+request table's hashed identifier, the original identifier is needed to send
+the notification. These fields are recoverable plaintext database values;
+protect access/backups and apply deployment encryption controls as appropriate.
+They are excluded from public request APIs, state-change hook snapshots, device
+snapshots and observation events. The normal request cleanup cascades deletion
+to delivery data. Credentials remain until request cleanup, including after
+successful delivery/collection, to avoid inventing a separate retention system.
+
+Approval/denial commits before notification. An outer application transaction
+delays notification until its outermost commit; rollback sends nothing. A
+successful send returns normally from completion. Network/non-200-or-204 errors
+raise PingDeliveryError **after** approval/denial is saved. If completion happens
+inside an outer transaction, that error arises from the outer commit. It does
+not mean the result rolled back. Observers remain independent best-effort hooks;
+notification failures are not suppressed as observation failures.
+
+`retry_ciba_ping(request_id)` sends separately from completion and returns
+`:delivered` or `:not_deliverable` for pending, consumed, expired or non-ping
+requests. Unknown IDs raise NotFound. It refuses execution inside a transaction.
+Each send uses the client's current registered HTTPS notification endpoint,
+matching node-oidc-provider's freshly loaded Client behavior. An authenticated
+registration-management update can therefore redirect subsequent notifications,
+including their saved notification credential, to the replacement endpoint.
+A client that no longer supports ping or has invalid metadata raises Ineligible.
+A request already constructed for dispatch keeps its selected endpoint even if
+management updates the registration during delivery; updates do not cancel
+in-flight network operations. Repeated identical completion retains the
+existing idempotent completion behavior; use the retry API to resend.
+
+Delivery is a POST with Bearer authentication and a JSON body containing only
+auth_req_id. Approval and denial have the same notification shape. The client
+authenticates separately to obtain tokens or the denial result. Failure to
+deliver does not prevent retrieval of an already saved result.
+
+There is no durable automatic retry scheduler or exactly-once claim. An
+application may schedule explicit retries. Concurrent retries can send duplicate
+notifications, and a result can be consumed/expire while a send is in flight.
+The receiver must deduplicate notifications by identifier before collecting
+tokens; fetching twice would trigger replay revocation. Process death after
+commit and before send is another reason to use application-managed retries.
+
+## Evidence and remaining work
+
+Integration tests cover approval/denial, exact payload, private snapshots,
+post-commit delivery, rollback, failed-send persistence, retry, expiry, metadata,
+endpoint changes and cascading cleanup. The installed-gem ping smoke uses a
+real HTTPS receiver with a temporary CA and an exact loopback policy exception;
+TLS verification stays enabled. It tests 200/204, 503/302, a stalled response,
+retry and collection. A separate process without trust in the test CA rejects
+TLS before credentials reach the receiver while retaining the saved result.
+The independent [node comparison](research/ping-reference-contract.md) establishes
+the reference save-before-send behavior.
+
+Barrier-based tests hold automatic delivery open while another DB connection
+collects tokens, and hold two explicit retries open during collection. There is
+no active DB transaction in the send callback; one token issuance occurs, both
+in-flight notifications may finish, and subsequent retry is not_deliverable.
+A duplicate token collection still revokes the grant. Signed requests with
+user_code use the signed notification token only, ignoring outer replacements.
+
+Process-crash recovery, multi-process delivery, hostname-mismatch/expired TLS
+certificates and every feature combination remain unverified. These scenarios
+do not establish full node parity or certification.
+
+### Notification response bodies
+
+A200 or204 status acknowledges delivery. The gem closes the response connection
+without reading its body, so an ignored body cannot fail delivery because of its
+size or a body-read timeout. TLS verification, endpoint/address validation,
+redirect rejection and the header-receipt timeout remain enforced. Other HTTP
+consumers (JWKS and sector documents) retain their bounded body reads.
+
+[Protocol/transport tests](validation/ping-response-body-current.txt) include a
+response declaring10MB but sending no body: the sender returns after headers
+and the peer observes closure. The [installed TLS fixture](validation/ping-response-body-installed.txt)
+and [reference TLS fixture](validation/node-ping-response-body.txt) both accept
+a200 response containing140,000 ignored bytes. Response-header stalls and failed
+statuses remain separate failures; successful headers do not require a complete
+response body.

data/docs/protocol-coverage.md

@@ -0,0 +1,114 @@
+# Protocol-to-test mapping
+
+Push is not implemented by the selected node-oidc-provider 9.12.2 reference or
+this gem. Its conditional requirements are retained as `reference_unsupported`,
+not passing tests. [Measured boundary](research/push-reference-boundary.md).
+
+Optional refresh/related revocation coverage is in `test/ciba_refresh_test.rb`,
+`test/ciba_refresh_storage_test.rb`, `test/ciba_refresh_permissions_test.rb`,
+`test/ciba_refresh_hooks_test.rb`, `test/ciba_access_revocation_test.rb` and
+`test/ciba_lock_order_test.rb`. It includes scoped issuance, source persistence,
+rotation/replay, current-consent filtering, transaction hooks, cleanup,
+access-versus-refresh revocation, token provenance and legacy formats. The
+installed extension smoke covers opaque/JWT combinations. See the
+[reference boundaries](research/access-token-revocation-reference.md) before
+interpreting these tests as full OAuth revocation or node behavior equivalence.
+
+Implementation extension (not a CIBA Core requirement): optional nonce propagation is tested by `test_nonce_is_bound_to_start_request_not_poll_and_not_observed`, `test_nonce_is_optional_and_bounded`, `test_nonce_forward_migration_preserves_existing_request` and the complete node HTTP harness. These tests do not add a CIBA conformance requirement.
+
+Additional optional capabilities have separate coverage: `test/ciba_claims_test.rb` tests explicit claim consent and UserInfo provenance; `test/ciba_resources_test.rb` tests per-resource scope/audience, omission callbacks, saved-consent and original-target binding, JWT/opaque UserInfo rejection, introspection, issuance rollback, concurrent target selection and claims composition. The full node OP harness independently covers comparable claims and resource scenarios. See [claims limits](claims.md) and [resource limits](resources.md); these are not a claim of full OIDC claims or RFC8707 conformance.
+
+This is the release's requirement mapping, not a certification claim. Run `ruby test/run.rb`; method names below are in `test/ciba_*_test.rb` unless otherwise noted. The implementation covers the declared subset; omitted optional features are not counted as passing tests.
+
+| Reference / concern | Test method(s) |
+|---|---|
+| CIBA §4: Discovery / poll metadata | `test_discovery_describes_poll_and_keeps_existing_oidc_metadata` |
+| CIBA §7, §7.1: TLS, form POST, confidential authentication | `test_non_tls_and_json_requests_are_rejected`, `test_client_authentication_is_required_at_both_endpoints`, `test_post_client_authentication`, `test_basic_credentials_are_form_decoded_and_hashed_secrets_work`, `test_two_authentication_methods_are_rejected` |
+| CIBA §7.1–7.2: hint, scope, unsupported features, unknown parameters | `test_request_validation_and_unknown_parameters` |
+| Optional login_hint_token resolver, exclusive hints, account binding and raw-token exclusion | `test/ciba_hint_token_test.rb`; complete node HTTP comparison and installed-gem extension smoke |
+| Optional id_token_hint signature/issuer/audience/time boundary, retained keys and new approval | `test/ciba_id_token_hint_test.rb`; complete node comparison; installed-gem extension smoke; [validation differences](id-token-hint.md) |
+| Optional signed request metadata, client keys, required claims and inner-only parameters | `test/ciba_signed_request_test.rb`, `test/ciba_remote_jwks_test.rb`; complete node comparison and installed-gem signed requests; [limits](signed-requests.md) |
+| Optional user_code application policy, missing/invalid errors, no raw persistence and new approval | `test/ciba_user_code_test.rb`; complete node comparison and installed-gem signed-request composition; [policy boundary](user-code.md) |
+| Optional request_context application callback, persistence, signed input, failure boundaries and no automatic token claim | `test/ciba_request_context_test.rb`; complete node HTTP harness and installed extension smoke; [contract](request-context.md) |
+| Optional ping: metadata, private delivery data, completion/notification ordering, retry, cleanup | `test/ciba_ping_test.rb`, installed-gem `examples/ping_smoke.rb`, independent node `test/reference/full-op/ping.mjs`; [limits](ping.md) |
+| CIBA §7.1: binding / requested expiry / context | `test_expiry_binding_context_and_offline_access` |
+| OAuth request parsing: repeated parameters / encoding / bounds | `test_duplicate_parameters_are_rejected`, `test_invalid_utf8_and_oversized_body_are_rejected`, `test_rack_inputs_without_rewind_work_on_both_endpoints` |
+| CIBA §7.3: acknowledgement / no-store | `test_expiry_binding_context_and_offline_access`, `test_approved_request_issues_customer_id_token_once` |
+| CIBA §10.1: client-bound request / subject | `test_other_identity_client_and_expiry_cannot_issue` |
+| CIBA §10.1.1 / OIDC Core §2: signed ID Token, issuer/audience/context | `test_approved_request_issues_customer_id_token_once`, `test_id_token_audience_is_client_even_with_different_access_audience`, `test_missing_authentication_context_is_not_fabricated`, `test_unsigned_id_token_client_is_rejected` |
+| CIBA §10.1.1: one successful redemption | `test_approved_request_issues_customer_id_token_once`, `test_concurrent_polls_issue_one_grant` |
+| CIBA §11: pending / slow_down | `test_pending_poll_updates_survive_json_halt`, `test_concurrent_pending_polls_both_receive_retryable_results` |
+| CIBA §11: denial / expiry | `test_denial_and_expired_completion`, `test_other_identity_client_and_expiry_cannot_issue`, `test_expiry_during_before_issue_rolls_back_and_returns_expired` |
+| App completion contract / retry / identity | `test_approval_is_idempotent_and_context_conflicts_are_rejected`, `test_concurrent_approve_and_deny_choose_one_decision`, `test_client_and_account_changes_are_rechecked` |
+| Signing and hook rollback / savepoints | `test_signing_failure_rolls_back_consumption_and_grant_then_allows_retry`, `test_hooks_see_before_and_after_states_and_failure_rolls_back`, `test_completion_hook_failure_rolls_back_and_retry_does_not_repeat_hooks`, `test_failure_reported_inside_outer_transaction_still_rolls_back_inner_work` |
+| Commit observations / rollback / callback failure | `test_observation_waits_for_outer_commit_and_does_not_change_result`, `test_outer_rollback_discards_issuance_and_observation`, `test_savepoint_rollback_discards_event_even_when_outer_transaction_commits`, `test_request_callbacks_after_commit_and_observer_secrets`, `test_acceptance_hook_rollback_does_not_notify` |
+| Reentrancy / immutable lookup / recovery / cleanup | `test_reentrant_completion_is_rejected_even_from_another_auth_instance`, `test_request_lookup_recovery_and_cleanup`, `test_expired_pending_cleanup_and_live_approved_retention` |
+| Schema / migration / uniqueness | `test_custom_table_and_column_mapping`, `test_migration_client_metadata_helper`, `test_explicit_migration_up_and_down`, `test_schema_rejects_duplicate_public_identifier` |
+| Upstream coexistence / initial restrictions | `test_authorization_code_flow_still_uses_oidc_wrapper`, `test_dcr_rejects_ciba_but_preserves_other_grant_validation`, `test_unavailable_or_unsupported_client_metadata_is_rejected`, `test_jwt_access_token_configuration_also_works` |
+| Demo's browser transport | `DemoTest#test_browser_approval_checks_csrf_and_finishes_request`, `test_default_require_loads_jwt_backend_in_fresh_process` |
+
+## Primary specifications
+
+- [CIBA Core 1.0](https://openid.net/specs/openid-client-initiated-backchannel-authentication-core-1_0.html)
+- [OIDC Core 1.0](https://openid.net/specs/openid-connect-core-1_0.html)
+- [RFC 6749](https://www.rfc-editor.org/rfc/rfc6749.html)
+
+Product policies (size limits, offline_access removal, static/public restriction, internal API semantics) are distinguished in [the API documentation](api.md). The test suite verifies those policies; it does not imply they are universally required by the specifications.
+
+## Conformance Suite cases consulted
+
+The following files were read from the OpenID Foundation's read-only mirror at commit `fc6a65c4ac25a7f1fc8a92205ebc5836f321189d` on2026-09-29:
+
+- [FAPICIBAID1AuthReqIdExpired](https://github.com/openid-certification/conformance-suite/blob/fc6a65c4ac25a7f1fc8a92205ebc5836f321189d/src/main/java/net/openid/conformance/fapiciba/FAPICIBAID1AuthReqIdExpired.java): requested lifetime followed by an expired collection attempt. The local tests use a controlled clock/DB deadline instead of sleeping.
+- [FAPICIBAID1EnsureAuthorizationRequestWithMultipleHintsFails](https://github.com/openid-certification/conformance-suite/blob/fc6a65c4ac25a7f1fc8a92205ebc5836f321189d/src/main/java/net/openid/conformance/fapiciba/FAPICIBAID1EnsureAuthorizationRequestWithMultipleHintsFails.java): multiple hints are rejected. Local coverage exercises login_hint combined with the other hint parameters.
+- [FAPICIBAID1EnsureAuthorizationRequestWithBindingMessageSucceeds](https://github.com/openid-certification/conformance-suite/blob/fc6a65c4ac25a7f1fc8a92205ebc5836f321189d/src/main/java/net/openid/conformance/fapiciba/FAPICIBAID1EnsureAuthorizationRequestWithBindingMessageSucceeds.java): ordinary binding-message success. The local suite validates storage and the demo displays the message with HTML escaping.
+
+These are references for overlapping behaviors only. Their FAPI profile setup is not implemented here. No Suite code is copied into the gem, and neither the complete Suite nor certification tests have been run.
+
+## Client authentication compatibility follow-up
+
+CIBA Core §4 shares the OP's `token_endpoint_auth_methods_supported` metadata; it does not require basic/post-only OP configuration. §7.1 requires registered client authentication and accepts issuer/token/backchannel audiences for JWT assertions at the Backchannel Endpoint.
+
+- `test_upstream_jwt_authentication_coexists_with_ciba_and_discovery`: private_key_jwt CIBA start/poll, all three start audiences, existing authorization_code, Basic CIBA on the same OP, unchanged Discovery support.
+- `test_ciba_jwt_authentication_rejects_wrong_audience_signature_and_mixed_credentials`: wrong audience/signature and duplicate authentication rejected.
+- `test_upstream_client_secret_jwt_works_for_ciba`: upstream shared-secret JWT start/poll.
+- `test_public_clients_can_exist_but_cannot_use_ciba`: public-client configuration is allowed for the OP, excluded from CIBA.
+
+These tests do not claim all upstream authentication mechanisms are validated. JWT client authentication is distinct from the opt-in signed CIBA authentication requests covered above. See the following additional integration boundaries.
+
+## Additional authentication and registration coverage
+
+| Boundary | Current evidence |
+|---|---|
+| JWT assertion issuer audience at refresh, wrong audience and replay | `test/ciba_assertion_refresh_test.rb`, `test/reference/full-op/assertion-refresh.mjs` |
+| Discovery retention of configured introspection, DPoP algorithms and mTLS capability | `test/ciba_discovery_extensions_test.rb`; installed smoke follows discovered URLs |
+| DPoP proof, nonce policy, replay, UserInfo, introspection and refresh | `test/ciba_dpop_test.rb`, `test/ciba_dpop_registration_test.rb`, `examples/dpop_smoke.rb`, `test/reference/full-op/dpop.mjs`; [contract](research/dpop-reference-contract.md) |
+| mTLS trust callbacks, exact certificate binding, opaque/JWT UserInfo and introspection, refresh | `test/ciba_mtls_test.rb`, `examples/mtls_smoke.rb`, `test/reference/full-op/mtls.mjs`; [contract](research/mtls-reference-contract.md) |
+| mTLS remote JWKS rotation, retrieval failure and recovery | `test/ciba_mtls_remote_test.rb`; installed `examples/mtls_smoke.rb` uses verified HTTPS and forced cache expiry |
+| mTLS registration policy and management replacement | `test/ciba_mtls_registration_test.rb`; node and installed TLS fixtures |
+| Dynamic registration/management, metadata, credentials and concurrency | `test/ciba_registration_test.rb`, `test/ciba_registration_remote_test.rb`, `examples/registration_smoke.rb`; [contract](research/registration-reference-contract.md) |
+| Pairwise subjects, hints, refresh, sector documents and management | `test/ciba_pairwise_test.rb`, installed `examples/ping_smoke.rb`; [contract](research/pairwise-reference-contract.md) |
+
+These rows map integration boundaries, not every normative requirement in the
+referenced RFCs. Application-owned endpoint aliases have distinct-port TLS
+coverage; arbitrary proxy/path rewriting and distributed cache behavior do not.
+Consult [release validation](release-validation.md) for the tested Ruby/DB
+combinations; file presence alone is not proof of a successful run.
+
+## Manual requirements and security review
+
+The historical 2026-09-29, 159-item initial-scope classification is in [requirements-audit.md](requirements-audit.md). Its excluded optional features do not describe the subsequently implemented extensions. An incremental [current audit overlay](requirements-audit-current.md) now records reviewed and pending IDs; the full normative re-audit remains incomplete; [the alignment roadmap](alignment-roadmap.md) tracks current evidence and gaps. Classification separates mandatory, conditional, recommended and optional behavior and identifies gem/upstream/application/client responsibilities. The Jev scores are historical inputs, not compliance evidence.
+
+Additional direct tests in `test/ciba_security_test.rb` cover OIDC Core §9 required assertion claims, issuer/subject/client binding, malformed assertions, missing client keys, short HMAC keys, replay across endpoints/flows, concurrent replay, bounded ledger cleanup and persistent slow_down growth. `test/ciba_requirements_test.rb` covers acknowledgement identifier format, exact expiry boundary, HTTP401 authentication errors, missing-vs-invalid scope and optional error-description ASCII constraints. See [security-review.md](security-review.md) for findings and test limits.
+
+## node-oidc-provider alignment
+
+`test/ciba_alignment_test.rb` verifies the v9.12.2 binding-message default and application replacement policy. The demo XSS/CSRF test explicitly relaxes that policy to continue checking output escaping. See [alignment progress](node-alignment.md); this is not a claim that the remaining API or protocol differences are resolved.
+
+`test/ciba_grant_test.rb` verifies persisted consent, client/account binding, requested/approved scope intersection, untrusted snapshot-field rejection, consent expiry/revocation at collection, issuance/revocation races, revocation after request cleanup, completion retries and transactional rollback. That file alone does not cover node-specific claim/resource/RAR consent. Separate tests cover those extensions; executed PostgreSQL/MySQL evidence is recorded in [release validation](release-validation.md).
+
+- AD initiation integration: `test/ciba_alignment_test.rb` verifies saved request handoff before response, synchronous completion, missing implementation/dispatch failure, and rejection before dispatch. This application callback is an implementation boundary, not a standardized CIBA approval HTTP API.
+
+- Shared OIDC issuance: `test_common_oidc_claim_provider_only_receives_approved_scopes` verifies account claims come from the upstream provider using effective consent scopes, without browser-session authentication-time lookup. Full claims-parameter consent and resource/RAR support remain outside this evidence.
+
+- Completion consistency: `test_grant_expiry_during_before_approve_does_not_record_approval` and `test_grant_revocation_during_before_approve_rolls_back_the_completion` check revalidation after transactional hooks. Demo tests cover saved consent reuse, conflicting decision rollback, and another customer’s request rejection.

data/docs/refresh-tokens.md

@@ -0,0 +1,151 @@
+# CIBA refresh tokens — implementation in progress
+
+Disabled by default. This branch implements the basic flow, but it is not yet a
+release-ready refresh implementation. The implemented revocation boundaries and
+legacy-format differences below still need the overall alignment review. Do not
+infer full reference parity from the existence of the flag.
+
+For development tests, explicitly create storage with
+`Rodauth::CibaSupport::Schema.create_refresh_tokens(db)` and configure
+`ciba_refresh_tokens_enabled true`. Register both the CIBA grant and
+`refresh_token` for the client, and allow `offline_access` in both OP and client
+scopes. Initial issuance requires `offline_access` in both the CIBA source and
+its saved consent, as well as the
+refresh grant registration, matching the reference default policy.
+
+`ciba_refresh_tokens_table` defaults to `:ciba_refresh_tokens` and
+`ciba_refresh_token_lifetime` to 14 days. Only the digest of an opaque, namespaced
+refresh token is stored. The source retains original scope/resources/claims/RAR,
+account/client, consent ID and authentication context separately from each access
+token. Short-lived CIBA request cleanup does not remove it.
+
+Updates validate the authenticated client, current grant registration, account,
+saved consent and enabled optional capabilities. Removing `offline_access` from
+the saved consent rejects subsequent refreshes with `invalid_grant` before
+rotation or issuance. Scope narrowing applies to the
+current access token, not the saved refresh source. Resource selection is computed
+against the current consent. Each update creates a new access-token record.
+
+When upstream JWT client authentication is enabled, `private_key_jwt` and
+`client_secret_jwt` accept the OP issuer as the assertion audience for CIBA
+refresh, as they do for initial CIBA token collection. The current token URL
+remains accepted. This extension applies only to the CIBA grant and reserved
+`ciba_rt_` refresh namespace; ordinary OAuth token requests retain their existing
+audience policy. Wrong audiences and assertion replay remain authentication
+failures. [Measured comparison](research/refresh-reference-contract.md#jwt-client-assertion-audience).
+
+For confidential clients the initial implementation follows node's default
+rotation policy: rotate after 70% of token lifetime, until one year after initial
+issuance. A fresh token can be reused. Rotation preserves consumed digests; reuse
+by the correct client revokes the saved consent and its linked access tokens, and
+therefore also invalidates successor refresh tokens. A different client's request
+does not revoke the rightful client's consent. Simultaneous rotation can produce
+one success followed by a replay response that invalidates the returned successor.
+
+Token consumption, rotation and issuance share the DB transaction. Signing failure
+rolls them all back, preserving the project's accepted atomic-issuance contract.
+This differs from node's nontransactional memory adapter. Existing non-CIBA OAuth
+refresh tokens continue through upstream's implementation and rotation policy.
+
+The flag can be disabled without querying the optional table for presented CIBA
+refresh tokens; their namespace causes `invalid_grant`. This namespace is reserved
+for the extension. Changing ordinary OAuth token generators to use `ciba_rt_`
+would conflict with that dispatch boundary.
+
+See the [reference contract](research/refresh-reference-contract.md) for measured
+reference behavior and the remaining tests. Current authentication context output
+follows the gem's CIBA ID Token behavior; it is not identical to node's optional
+claim masking.
+
+## Refresh-token revocation
+
+Enable upstream `:oauth_token_revocation` to expose its advertised endpoint.
+The CIBA extension also adds its URL to OIDC Discovery when that feature is enabled.
+Presenting a `ciba_rt_` token authenticates the OAuth client (never the browser
+account), requires the CIBA form/TLS transport and revokes the entire saved
+consent and linked access tokens. This remains possible with refresh issuance
+disabled when the refresh table exists. The standard upstream before/after revoke
+hooks run in the transaction; an exception rolls the revocation back.
+
+Like the measured reference, missing, wrong or unknown `token_type_hint` does not
+prevent finding a CIBA refresh token. Success is HTTP 200 with an empty body.
+Unknown, expired and already-revoked tokens are successful no-ops. An authenticated
+different client presenting a live token receives `invalid_request`; it cannot
+revoke the owner's consent. After revocation, its retry is also a successful no-op.
+
+The endpoint also recognizes saved opaque CIBA access tokens independently of the
+hint. Their revocation invalidates related tokens and deletes old request/refresh
+sources while retaining saved consent, matching the [reference's distinct AT
+policy](research/access-token-revocation-reference.md). Standard transactional
+revoke hooks still apply. New opaque CIBA tokens use the reserved `ciba_at_`
+namespace, so unknown or cleaned-up tokens return empty 200 after client
+authentication. Legacy unprefixed tokens need a saved row to be recognized; after
+row cleanup they retain upstream behavior. Calling the consent-revocation API
+instead would not preserve consent.
+
+New CIBA JWT access tokens always carry the signed private issuance ID, even with
+explicit claims disabled. It is removed from ID Tokens. At revocation the marker
+selects a rejecting path, then OP signature/issuer/type are verified. Proven CIBA
+JWTs return `unsupported_token_type`, including expired ones; forged markers
+return `invalid_request`. This provenance-only verifier never authorizes token use
+and does not alter the normal access-token time checks. Node instead rejects all
+structured JWTs by header shape; unrelated and unmarked legacy JWTs keep upstream
+behavior here. No JWT revocation path mutates saved consent.
+
+The issuance marker also binds new JWT UserInfo access to its saved token row.
+Deleting that row invalidates UserInfo access. Unmarked historical JWTs retain the
+old scope-based path without borrowing explicit claims from another issuance.
+
+## Claims, authorization details and cleanup
+
+Opaque and JWT access-token tests cover claims/RAR with rotation. The original
+request fields are preserved in the successor source; the application's RAR
+policy is re-evaluated against saved consent for each update. A token-time claims
+parameter does not grant additional attributes. Current rejected claims suppress
+attribute reads and output, and disabled capabilities reject updates instead of
+silently dropping restrictions. Invalid RAR narrowing rolls rotation back.
+
+The reference test application's policy emits `source.rar`, explicitly supplied
+at completion; it ignores token-time expansion. The gem's test policy intersects
+the saved request and current consent, with optional narrowing. These are different
+application-owned policies, not proof of identical arbitrary RAR semantics.
+
+Run `cleanup_ciba_refresh_tokens(limit: 100)` from an application-owned maintenance
+job after creating the refresh table. It deletes at most the limit of sources whose
+expiry is at or before the current time, and returns the deleted count. Unexpired
+consumed sources must remain for replay detection. Cleanup does not delete saved
+consent or access tokens. It participates in an outer DB transaction and does not
+schedule itself.
+
+## Update hooks and events
+
+`before_ciba_refresh` and `after_ciba_refresh` run inside the token transaction.
+They can use `ciba_current_refresh`, an immutable snapshot of the presented refresh
+source with its digest removed. This is not a CIBA request snapshot: its `id` is
+the refresh-source row ID. The after snapshot reflects consumption of that source
+when rotation occurred. Neither snapshot includes a raw token. It is cleared on
+exit, and same-source reentrant updates are rejected.
+
+The source, account, client registration, saved consent, expiry and enabled
+capabilities are revalidated after the before hook. Hook exceptions roll back
+source consumption, successor creation and access-token issuance. As with other
+transactional hooks, external side effects cannot be rolled back by the gem.
+
+A successful update schedules an immutable `token_refreshed` observation event
+after the outermost commit. It has `version`, `event_id`, `type`, `occurred_at`,
+`refresh_token_id`, `grant_id`, `account_id`, `oauth_application_id` and `rotated`.
+It has no `request_id` because refresh can outlive request cleanup. Tokens, token
+digests, claims and authorization details are not included. Observer exceptions
+go through `report_ciba_observer_error` and do not change the committed result.
+This event describes a committed issuance, not proof of delivery to the client.
+
+## Installed artifact verification
+
+`bin/verify-package` builds and installs the gem in a temporary directory, clears
+checkout load-path variables and verifies that the feature is loaded from that
+installation. The extension smoke runs both opaque and JWT modes with signed
+authentication requests, claims/resources/RAR and refresh enabled. It verifies
+original identity context, rotation, grant replay revocation invalidating a
+successor, Discovery-based refresh revocation and expiry cleanup. Existing basic
+and real HTTPS ping smoke also run. Dependencies are reused from local installed
+gems; fresh network dependency resolution and publication are not tested.

data/docs/release-readiness.md

@@ -0,0 +1,75 @@
+# 0.1.0 release readiness
+
+RubyGems publication is pending. This document separates the supported release
+scope from historical development notes and opt-in experiments.
+
+## Scope
+
+The default integration uses poll, login_hint, public subjects and static
+confidential client registration. The README and individual feature contracts
+specify optional capabilities and application responsibilities. Refresh tokens,
+pairwise subjects and dynamic CIBA registration remain experimental, disabled by
+default and excluded from the initial supported release scope. Push and encrypted
+ID Token hints are not implemented. This is not OpenID Certified.
+
+The gem requires Ruby >=3.3 and the dependency versions in its gemspec. Application
+DB adapters, account/OAuth schemas, trusted identity resolution, approval UI,
+notification transport and business authorization are application responsibilities.
+
+## Published baseline evidence
+
+The [authentication-fix commit](https://github.com/kajisha/rodauth-ciba/commit/3791a53caae7ab6fbe6793fdb1646d7e5074c951)
+passed [hosted CI](https://github.com/kajisha/rodauth-ciba/actions/runs/36710533803):
+Ruby 3.3/3.4/4.0 SQLite and the Docker SQLite/PostgreSQL/MySQL job.
+Its local full run passed410 tests /10,844 assertions with two existing SQLite
+row-lock skips. The latest pre-release cleanup verification is recorded below.
+
+Jev's3.95/4 score (confidence0.96) concerned only the missing-client-authentication
+fix. It is not an overall conformance score or a release gate.
+
+## Cleanup review
+
+- README, CHANGELOG and the release goal now distinguish the current release
+  scope from intermediate implementation restrictions. Original changelog notes
+  are preserved in the repository's pre-release development history.
+- The gemspec declares homepage, source, issue tracker and changelog URLs.
+- Static method, constant and instance-variable reference searches were checked
+  against Rodauth's dynamic hooks, upstream overrides and public migration APIs.
+  A single textual occurrence alone is not evidence of dead code.
+- Removed an unreachable recipient-nil check and safe navigation in ID Token
+  encryption. The candidate array is local and checked for emptiness before
+  min_by, so successful selection always returns a pair.
+- No broad authentication/state-machine refactor was justified for this release.
+  Existing security boundaries and separate extension modules are retained.
+
+Test execution information is used to identify review candidates, not to prove
+that every unused branch is dead or every feature combination is covered.
+
+## Current cleanup verification
+
+The full suite before the one-line recipient-selection simplification passed410
+tests /10,844 assertions, zero failures/errors, with two existing SQLite row-lock
+skips. Runtime line coverage recorded2369 of2449 executable library lines;
+13 uncalled method definitions were application-overridden callbacks or default
+error reporters, not unused APIs. All other recorded library method definitions
+were exercised. This is execution evidence from Ruby4.0.6/SQLite, not branch
+coverage or proof of absence of dead code.
+
+[Full test log](https://github.com/kajisha/rodauth-ciba/blob/main/docs/validation/release-code-review-tests.txt)
+and [per-file execution summary](https://github.com/kajisha/rodauth-ciba/blob/main/docs/validation/release-code-coverage.json)
+are kept in the repository. Line locations refer to the pre-cleanup source.
+
+After removing the redundant check, the encryption regression selection passed
+76 tests /4,873 assertions, zero failures/errors, with one existing SQLite skip
+([log](https://github.com/kajisha/rodauth-ciba/blob/main/docs/validation/release-encryption-cleanup-tests.txt)).
+The selection includes the shared integration tests loaded by these test files.
+
+The updated gem passed `bin/verify-package`: build, temporary installation outside
+the checkout, and all installed HTTP/TLS smoke flows
+([log](https://github.com/kajisha/rodauth-ciba/blob/main/docs/validation/release-cleanup-package.txt)).
+Dependencies were reused from local installations; this does not test fresh
+network dependency resolution. After recording these results, the artifact was
+rebuilt with identical runtime code and updated documentation; its final SHA256
+is in `pkg/rodauth-ciba-0.1.0.gem.sha256` (local build output, not committed).
+The cleanup has not rerun the full Ruby/DB matrix locally; the hosted results
+above are for the preceding commit.