rodauth-ciba 0.1.0

data/docs/research/pairwise-reference-contract.md

@@ -0,0 +1,264 @@
+# Pairwise CIBA reference contract
+
+Reference: installed node-oidc-provider 9.12.2, compared with rodauth-oauth 1.7.0
+and the current gem. This is an implementation workstream, not a support claim.
+
+## Measured behavior
+
+`test/reference/full-op/registration-remote.mjs` now enables subjectTypes public
+and pairwise, with an explicit application pairwiseIdentifier callback. The
+callback uses HMAC over a JSON array of sector and account for the fixture; this
+is application policy, not a node default or an algorithm mandated by CIBA.
+
+The real registration and CIBA endpoints demonstrate:
+
+- Pairwise plus Basic authentication is rejected with invalid_client_metadata.
+- private_key_jwt with only inline JWKS and no jwks_uri is rejected.
+- A CIBA/authorization-code hybrid with response_types code but without
+  sector_identifier_uri is rejected.
+- Two CIBA-only private_key_jwt clients with the same jwks_uri are registered,
+  authenticated against a real local JWKS server, approved via separate saved
+  Grants, and obtain ID Tokens. OP signatures, issuer and client audience are
+  verified. Both subjects differ from the internal account ID and match each
+  other under the configured same-sector application policy.
+
+[Execution log](../validation/node-registration-remote-reference.txt).
+This does not yet test different sectors, hint inversion, hybrid completion or
+sector document validation through HTTP.
+
+## Source boundaries that affect the gem
+
+`lib/helpers/client_schema.js` requires jwks_uri for pairwise CIBA and an
+explicit sector URI when response_types is nonempty. It permits private_key_jwt
+or self_signed_tls_client_auth for such clients. Self-signed TLS is now implemented and verified separately in the
+[mTLS contract](mtls-reference-contract.md#pairwise-self-signed-tls-client-authentication).
+
+`lib/helpers/sector_identifier.js` selects the sector URI's URL.host when given.
+For a CIBA-only client without that URI it selects jwks_uri's URL.host. URL.host
+includes a nondefault port. Hybrid clients use the explicit sector URI because
+registration requires it. `lib/helpers/sector_validate.js` validates a fetched
+array: all redirect URIs (when applicable) and the client's jwks_uri must appear.
+The application's sectorIdentifierUriValidate policy controls this fetch.
+
+Node's default pairwiseIdentifier raises until configured. Its CIBA hint code
+(`lib/actions/authorization/ciba.js`) verifies id_token_hint and then passes its
+sub to findAccount. It does not invert a hash itself. The application must map
+that pairwise subject to its canonical account in the authenticated client's
+context; returning the pairwise string as a new account would change identity.
+This source observation has not yet been covered by the fixture's hint flow.
+
+Upstream Ruby `oidc.rb#jwt_subject` instead derives a missing sector from
+redirect_uri and hashes host, account ID and its configured secret. A CIBA-only
+client need not have redirect_uri, so removing the gem's public-only guard is
+insufficient. An opt-in CIBA wrapper now supplies the sector/callback boundary; the public-only
+default remains. The initial integration and remaining verification are described
+in [pairwise.md](../pairwise.md).
+
+## Implementation requirements
+
+1. Opt-in pairwise capability with an explicit application identifier callback,
+   leaving the current public default intact. Subject generation must work for
+   ID Token, UserInfo, access-token claims and refresh without changing unrelated
+   OAuth clients' subject handling.
+2. Validate the pairwise client authentication/URI requirements on static use,
+   dynamic registration and management replacement. Derive the CIBA-only sector
+   from jwks_uri; handle explicit sectors and hybrid clients with the reference's
+   document-membership rules and bounded outbound transport.
+3. Pass the authenticated client and selected sector to identifier generation;
+   reject unusable callback results. Avoid pretending a hashing function supplies
+   the application's persistence, stable-key lifecycle or identity mapping.
+4. Keep internal account IDs in saved requests/consents. ID Token hint resolution
+   must recover that account through the existing application resolver, followed
+   by the ordinary account/client/consent checks. A hint must not grant approval.
+5. Verify same-sector stability, different-sector separation, hints, UserInfo,
+   refresh, invalid registration and management updates, plus ordinary public
+   clients. Compare real node and gem scenarios before advertising support.
+
+The approved staged plan still includes this whole boundary. Registration-only
+acceptance is not completion of pairwise alignment.
+
+
+## Refresh integration
+
+The real node fixture now requests offline_access for pairwise clients and
+verifies refreshed ID Token signatures, stable subject, matching UserInfo and
+canonical accountId on the saved RefreshToken. offline_access does not become
+a UserInfo attribute.
+
+The gem's opaque/JWT integration additionally checks forced refresh rotation,
+old-token replay revoking the successor, refusal to exchange through another
+client, and transaction rollback for nil/empty/non-ASCII/overlong identifier
+callback results. Refresh source and OAuth token counts remain unchanged after
+failed issuance, and a subsequent valid callback can issue successfully.
+
+This exposed upstream UserInfo passing offline_access to its generic attribute
+callback and raising when no custom callback exists. CIBA's non-projected account
+claim path now removes that capability scope before delegation, preserving other
+scopes and unrelated OAuth behavior. The fix is shared by opaque/JWT tokens.
+[Reproduction](../validation/pairwise-refresh-red.txt),
+[DB validation](../validation/pairwise-refresh-matrix.txt).
+
+
+## Real HTTPS sector documents and installed artifact
+
+The installed gem reuses the existing TLS fixture in `examples/ping_smoke.rb`.
+A hybrid pairwise client is registered through the real upstream DCR route with
+jwks_uri and a redirect URI in its sector document. Missing either URI, invalid
+JSON/object shape, oversized body, 503 and 302 are rejected without creating a
+client. The untrusted-certificate child process rejects registration before the
+HTTPS application handler receives a request. No registration bearer is sent to
+the document host. All existing installed-package smoke scenarios also pass.
+[Artifact execution](../validation/pairwise-sector-package.txt).
+
+The node TLS fixture in `test/reference/full-op/ping.mjs` now measures the same
+membership/JSON/error cases. It **follows** same-origin 302 and accepts a valid
+resulting document; the gem's bounded transport refuses redirects. This is a
+newly measured remaining difference, not evidence of full transport parity.
+A future redirect implementation must validate every destination and bound the
+whole operation; changing the transport globally would also affect ping, whose
+measured contract rejects redirects. Cross-origin redirects were not tested.
+[Node execution](../validation/node-sector-tls-reference.txt).
+
+The fixture generates and trusts an ephemeral CA in a child process only. No
+production trust-store modifications or external service calls are involved.
+Installed dependencies are reused; clean network dependency resolution is not
+part of this artifact test.
+
+
+## Sector redirect implementation
+
+The previously measured 302 difference is now repaired in the sector fetch path.
+It follows 301/302/303/307/308 with relative URI resolution, at most 20 redirects,
+and an outer 2.5-second deadline for the entire chain. Each hop calls the existing
+bounded transport with the same address policy and a fresh unauthenticated GET.
+Invalid schemes, credentials in URLs, blocked destinations, loops and timeouts
+are refused. The shared HTTP primitive and ping/JWKS behavior are unchanged.
+
+The installed TLS fixture now accepts a valid redirected document and rejects
+loops, file URLs and a redirected address outside its test allowlist without
+client persistence or bearer forwarding. Unit tests cover all five statuses,
+cross-origin dispatch through the policy, exact loop bounds, invalid URI forms
+and an actual elapsed-time timeout spanning repeated stubbed responses.
+[Installed artifact](../validation/sector-redirect-package.txt),
+[DB tests](../validation/sector-redirect-matrix.txt).
+The node same-origin 302 observation remains the comparison evidence. Arbitrary
+cross-origin live TLS deployments, IDN host normalization, sector-document cache
+lifecycle and registration-management effects remain separate work.
+
+
+## Sector validation lifecycle
+
+Source inspection located node sector validation in add_client, Client.validate,
+and the first static-client lookup. Dynamic lookup hashes stored metadata and
+reuses a Client in a 100-entry LRU. The real TLS fixture confirms an unchanged
+loaded client survives a sector endpoint 503 without another fetch; changed
+management metadata fails revalidation, preserving the old client/credential,
+and succeeds when the endpoint recovers.
+
+The gem now stores successful validation in a per-Rodauth-class 100-entry LRU
+keyed by a SHA-256 digest of the complete DB client row. A cold lookup fetches;
+warm unchanged metadata does not. Registration and management always validate
+fresh. Failed attempts are never cached or used to invalidate an old success.
+The bounded map uses a mutex only around cache operations, not HTTP. Concurrent
+cold misses may duplicate fetches; no cross-process cache guarantee is made.
+Using the full DB row means app-owned column changes also trigger revalidation,
+unlike a cache keyed only by protocol metadata. Static clients share this bound,
+whereas node maintains a separate static-client map. These are explicit storage
+adaptations, not proof of identical eviction in every deployment.
+
+[Node lifecycle evidence](../validation/node-sector-tls-reference.txt),
+[gem DB tests](../validation/sector-cache-matrix.txt),
+[installed TLS regression](../validation/sector-cache-package.txt).
+Tests cover warm reuse, failed refresh, changed metadata, recovery, and eviction
+past 100 entries. Pending/issued token behavior after sector changes is still a
+separate unfinished comparison.
+
+
+## Management sector changes and issued subjects
+
+The real node fixture now changes a registered pairwise client's jwks_uri to a
+second owned loopback server with a different port (thus a different sector).
+The existing opaque token still obtains UserInfo, whose sub uses the new sector.
+Refresh produces a verified ID Token with that new sub. Old signed tokens are
+not rewritten. This outcome is fixed in the reference assertions.
+
+Gem opaque tokens already matched; JWT tokens failed because the original signed
+sub was compared with a recomputation using new metadata. The explicit nullable
+`Schema.add_pairwise_subject` migration now records the issuance subject on each
+new CIBA token row while pairwise is enabled (including public subjects).
+Claims use the saved issuance value; UserInfo authenticates the JWT against that
+value and then emits the current client's pairwise sub. Invalid signed-subject
+substitutions are still refused. The DB/internal account remains unchanged.
+Configuration requires the column before enabling pairwise. Legacy null rows
+use the earlier current-subject comparison and may fail after sector changes;
+there is no automatic historical backfill.
+
+The gem tests perform real authenticated management PUT after refresh rotation,
+then test old-token UserInfo, new refresh subject, and replay revocation for both
+opaque and JWT variants. [Initial JWT failure](../validation/pairwise-sector-update-red.txt),
+[DB suite](../validation/pairwise-sector-update-matrix.txt),
+[reference OP](../validation/node-registration-remote-reference.txt).
+The node comparison uses opaque access tokens. Its JWT resource-token profile is
+not a UserInfo token profile, so this is a gem adaptation preserving its existing
+JWT UserInfo capability, not a claim of identical token formats.
+
+
+## Pending requests and installed issuance
+
+Both real node and gem fixtures now start a request before changing the client's
+sector through authenticated management PUT. The pending record keeps its
+canonical account and no grant; the update does not supply approval. Subsequent
+application approval and token collection produce a verified ID Token using the
+new sector subject. The gem opaque/JWT variants pass on three databases.
+[DB comparison](../validation/pairwise-pending-matrix.txt),
+[node comparison](../validation/node-registration-remote-reference.txt).
+These are sequential transitions, not proof of all concurrent interleavings.
+
+The installed-gem TLS fixture now goes beyond registration: a hybrid pairwise
+client authenticates using private_key_jwt against real HTTPS JWKS, begins a
+CIBA request, receives application approval, obtains an issuer/audience/signature
+verified ID Token, persists its issued subject and returns the matching UserInfo
+subject. It explicitly migrates both subject storage and the assertion replay
+ledger. Trusted and untrusted certificate cases remain separate child processes.
+[Artifact evidence](../validation/pairwise-issuance-package.txt).
+This installed pairwise flow uses opaque access tokens; JWT/refresh variants
+are covered in the DB integration suite, not this specific installed example.
+
+## Management changes overlapping issuance
+
+Two gem tests now cover management PUT during opaque/JWT issuance. PostgreSQL
+and MySQL pause issuance after it loads the client and force management to commit
+before token generation resumes. Both tokens and the stored issuance subject
+retain the old sector, while subsequent UserInfo uses the new sector. Only one
+OAuth grant is created and the request is consumed. SQLite uses simultaneous
+requests without a cross-writer commit barrier, accepts either serial order,
+and checks the same token/storage consistency; a temporary busy response may
+be retried with a fresh client assertion.
+
+All three databases pass: SQLite **2 tests / 21 assertions**, PostgreSQL and
+MySQL each **2 tests / 19 assertions**. [Log](../validation/pairwise-concurrent-matrix.txt).
+No runtime change was needed. This validates the gem's same-DB issuance boundary;
+it is not a concurrent reference-OP comparison. Client deletion, authentication
+key replacement, refresh and arbitrary application hooks during these pauses are
+not covered by these two sector-update cases.
+
+## Signed requests do not replace pairwise client authentication
+
+The pinned 9.12.2 client schema unconditionally restricts pairwise CIBA clients
+to private_key_jwt or self_signed_tls_client_auth. Enabling
+backchannel_authentication_request_signing_alg does not waive that condition.
+A real HTTP DCR regression registers a public-subject Basic client with RS256
+request metadata and remote jwks_uri successfully, then rejects the same
+metadata with pairwise using invalid_client_metadata and the explicit
+client-authentication-method error. The provider explicitly enables both subject
+types so an unsupported-subject rejection cannot satisfy the test.
+
+The gem regression accepts the same public configuration and rejects its
+pairwise counterpart without saving a client. No runtime change was needed.
+Earlier notes treated signed-request-only proof as unfinished parity; that
+classification was incorrect. It is a shared restriction of the selected
+reference policy. This registration test does not claim to exercise a signed
+CIBA authentication request or all authentication methods.
+
+[Node 24 / pinned provider execution](../validation/node-pairwise-signed-auth-policy.txt),
+[gem: 1 test, 4 assertions](../validation/pairwise-signed-auth-policy.txt).

data/docs/research/ping-reference-contract.md

@@ -0,0 +1,165 @@
+# Ping delivery boundary
+
+2026-09-30. Reference: released node-oidc-provider 9.12.2, Node24.21.0,
+complete HTTP OP plus a real HTTPS notification receiver. The gem now supports
+optional [ping](../ping.md) as well as poll; the following evidence defined the
+implementation boundary and still records remaining review criteria.
+
+## Measured behavior
+
+[Test](../../test/reference/full-op/ping.mjs),
+[full reference log](../validation/node-full-op-lts.txt).
+
+| Scenario | Reference outcome |
+|---|---|
+| Missing notification token, spaces in token, >1024 characters | invalid_request |
+| Accepted request before completion | No notification; token request returns authorization_pending |
+| Approval | Save result, then POST notification; token retrieval remains a separate authenticated request |
+| Denial | Same notification shape, followed by access_denied at token endpoint |
+| Notification contents | Bearer client_notification_token; application/json with only auth_req_id |
+| Receiver returns 200 or 204 | Delivery succeeds |
+| Receiver returns 503 | Completion call raises; saved grant binding remains |
+| Receiver returns 302 | Completion call raises; redirect is not followed |
+| Delivery retry | Client.backchannelPing(savedRequest) sends explicitly without recompleting approval |
+| Token retrieval after failed delivery and explicit retry | Succeeds from the saved result |
+| Loopback notification destination under default transport | Rejected by special-use-IP protection before receiver obtains the HTTP request |
+
+`Provider.backchannelResult` saves before calling `Client.backchannelPing`.
+The sender accepts 200/204, uses manual redirects and has no built-in durable
+retry queue. Source sets a 2500ms fetch timeout; delayed-network timeout behavior
+was not measured here. The default transport checks the connected socket's IP
+against special-use ranges, rather than relying only on registration syntax.
+
+The harness first proves loopback rejection. It then allows exactly its owned
+HTTPS endpoint through a test-only fetch override, retaining certificate
+verification, timeout and redirect policy. A temporary self-signed test CA is
+trusted only by the test process. The override is not production configuration
+or evidence of delivery to a publicly routed endpoint.
+
+## Protocol requirements
+
+[CIBA Core sections 4, 7.1, 9 and 10.2](https://openid.net/specs/openid-client-initiated-backchannel-authentication-core-1_0.html)
+define registered ping mode and an HTTPS client notification endpoint, the
+request's client_notification_token, and notification using that bearer token
+with the auth_req_id. The client subsequently authenticates at the token
+endpoint. Notification does not deliver access or ID tokens.
+
+## Gem implementation boundary
+
+1. Opt-in ping alongside default poll; explicit client-metadata/storage migration
+   and accurate Discovery. Preserve existing poll clients and pending requests.
+2. Validate the registered endpoint and bearer-token syntax/size before request
+   persistence. Registered destinations need network-level protection, not just
+   an HTTPS prefix check. Do not follow redirects or use request-supplied URLs.
+3. Persist sufficient private delivery data. Current requests store only a hash
+   of auth_req_id, which cannot produce the notification body. Both the original
+   ID and notification credential must survive completion by another worker.
+   Exclude these from all public request APIs, hook snapshots and observations;
+   define cleanup/retention and any storage-protection requirements explicitly.
+4. Save approval/denial transactionally, send only after the outermost commit,
+   and leave that result intact on delivery failure. Retain the agreed Rodauth
+   rollback behavior for before/after state-change hooks. Network delivery must
+   not occur while holding the request's DB transaction/row lock.
+5. Provide explicit notification retry, separate from completion; do not add an
+   automatic queue or claim exactly-once delivery. A delivery failure does not
+   invalidate a saved approval. Handle response loss, duplicate notification,
+   expired/consumed requests and concurrent retry explicitly in tests/docs.
+6. Keep token issuance/replay revocation and customer/client binding unchanged.
+   Test full acceptance, approval, denial, delivery and token collection using
+   an independent TLS receiver and the installed gem, including failure cases.
+
+The initial comparison found the gem's registered remote-JWKS helper lacked
+node's special-use-IP guard. The [dedicated CIBA transport](../outbound-http.md)
+now checks DNS answers and pins a validated address; its limits and different
+policy are documented. Unrelated OP HTTP routes remain unchanged. This closes
+part of the transport gap, not ping delivery itself.
+
+The research increment itself did not implement ping. The subsequent optional
+implementation adds private delivery storage, after-commit notification and
+explicit retry. Production egress policy and concurrent delivery remain review
+work; the feature documentation records credential retention and failure behavior.
+
+## Ignored response body parity
+
+The shared HTTP transport previously read up to65,536 bytes even for ping,
+turning a valid200 acknowledgement with a larger ignored body into a delivery
+failure. Node's notification method checks status without consuming the body.
+The gem now requests headers-only handling for ping and closes its Net::HTTP
+connection through the normal start/ensure cleanup. It does not follow redirects
+or disable certificate/address validation. Key and sector fetches still read and
+bound their bodies.
+
+The real TCP test sends200 headers declaring10MB and never sends a body, then
+observes peer closure; this proves the Ruby path does not implicitly drain.
+Both installed gem and pinned Node TLS fixtures now send140,000 bytes on200 and
+pass. [Local12 tests /113 assertions](../validation/ping-response-body-current.txt),
+[installed artifact](../validation/ping-response-body-installed.txt),
+[reference TLS](../validation/node-ping-response-body.txt).
+The artifact also reruns oversized sector/JWKS rejection and untrusted TLS
+scenarios, so the ping exception does not remove their protections.
+
+## Initial management-update comparison (superseded below)
+
+The gem snapshots the endpoint at request acceptance and checks current client
+metadata before each dispatch. A deterministic barrier test now performs actual
+registration-management PUT requests while completion's sender is paused. Both
+endpoint replacement and switching to poll preserve the already approved result;
+a subsequent retry raises Ineligible without sending, token collection succeeds
+once, and replay is rejected. The in-flight sender retains only the original
+endpoint and notification credential and runs outside a database transaction.
+This is not atomic cancellation of a network operation.
+
+Source comparison: provider9.12.2's `Client.backchannelPing` in
+`lib/models/client.js` takes its destination from the Client instance on which it
+is invoked, and the credential from the saved authentication request. It has no
+comparison with an acceptance-time endpoint in that method. Consequently the
+gem's snapshot check is a deliberate stricter credential-routing policy, not a
+claim of identical management-update semantics. The real HTTP management race is now measured below.
+
+[Gem barrier test](../../test/ciba_ping_test.rb),
+[local execution](../validation/ping-management-current.txt).
+
+[Three-database execution](../validation/ping-management-matrix.txt): three tests,
+42 assertions per database, no failures/errors/skips.
+
+### Reference HTTP management race
+
+[Execution](../validation/node-ping-management.txt) uses provider9.12.2 with
+actual authenticated registration and management PUT, and the existing verified
+TLS receiver. A promise barrier pauses completion at the configured fetch
+transport before the network request. The management update completes before
+the barrier is released; no timing sleeps determine ordering.
+
+| Update while completion is dispatching | Reference result | Gem result |
+|---|---|---|
+| Replace notification endpoint | In-flight send uses original endpoint; retry on a freshly loaded Client sends the saved bearer credential and request ID to the replacement endpoint | In-flight send uses original endpoint; subsequent retry raises Ineligible |
+| Switch ping to poll | In-flight send uses original endpoint; retry on fresh Client raises TypeError without sending | In-flight send uses original endpoint; subsequent retry raises Ineligible without sending |
+| Collect completed result after either update | First token request succeeds; repeated request returns invalid_grant | Same |
+
+This establishes a concrete remaining policy difference, not failed CIBA token
+issuance or unknown behavior. Matching the reference on endpoint replacement
+would require changing the gem's acceptance-time destination binding and its
+documented credential-routing guarantee. It has not been silently relaxed.
+The current test does not establish cancellation, distributed-client cache
+coherence, or every possible ordering of management and dispatch.
+
+### Alignment correction: current registered destination
+
+The earlier snapshot restriction was an extra gem policy, not a requirement
+established by the reference. To follow the requested reference design,
+`retry_ciba_ping` now reads the current eligible client's registered endpoint
+when constructing each outgoing request. The saved endpoint column is retained
+for schema compatibility but no longer controls routing. This replaces the
+gem outcomes in the endpoint-replacement row above: subsequent retries now
+reach the replacement endpoint with the saved credential, as the reference does.
+
+Mode changes to poll still reject retries. Existing sends retain their selected
+endpoint; result persistence and single token collection are unchanged. HTTPS
+metadata validation, DNS/IP filtering, verified TLS and redirect rejection remain
+active. Registration-management authority includes authority to receive pending
+notification credentials at a replacement endpoint, matching the reference.
+
+The updated tests first reproduced the old Ineligible failures
+([red](../validation/ping-current-endpoint-red.txt)).
+All ping tests then passed on three databases
+([execution](../validation/ping-current-endpoint-matrix.txt)).

data/docs/research/rar-reference-contract.md

@@ -0,0 +1,55 @@
+# RAR in the CIBA reference OP
+
+Implementation update: the gem now has [optional RAR integration](../authorization-details.md), including registered/client type checks, saved consent, mandatory validation/issuance policy, output validation, JWT/token-response/opaque-introspection representation and ID Token exclusion. Tests now also race different narrowing requests and issuance/revocation on distinct DB connections. The earlier foundation and design notes below describe the implementation sequence; completion concurrency and additional policy/load-order review remain.
+
+2026-09-30. Tested the installed, released node-oidc-provider 9.12.2 with a complete HTTP OP on Node24.21.0. RAR is enabled explicitly with a test-only `support_data` type, registered client permission for that type, and explicit application policy callbacks. The resource server uses opaque tokens for the introspection case. This is not a gem feature announcement.
+
+## Observed behavior
+
+| Scenario | Reference result |
+|---|---|
+| A client without the requested authorization-details type | `invalid_authorization_details` |
+| A valid RAR request without a resource or configured default | `invalid_target` |
+| Initial request with read/delete actions | Original JSON is stored in `BackchannelAuthenticationRequest.params`; source `rar` is absent |
+| A saved Grant contains read-only `rar`, but completion omits `rar` | Token response has no authorization_details; neither the grant-source nor access-token policy callback ran in this case |
+| Completion explicitly supplies read-only `rar` | Source carries that permission; access-token policy runs |
+| Token request tries to add delete | The test application's policy returns only completed-source details, so the token response and opaque introspection contain only read |
+| ID Token in the successful RAR flow | No authorization_details claim |
+| Non-array JSON, unknown type, actions as a string | `invalid_authorization_details` |
+
+The token-time narrowing result depends on the configured application callback. It is not evidence that the library automatically compares arbitrary JSON, intersects `Grant.rar`, or enforces all type-specific constraints. The fixture deliberately implements a simple policy that ignores token-time broadening and returns the previously completed source permission.
+
+Evidence: [executable complete-OP harness](../../test/reference/full-op/lifecycle.mjs), [execution log](../validation/node-full-op-lts.txt). Earlier lifecycle, claims and resource cases still pass with RAR configured.
+
+## Where the boundaries live
+
+- `lib/shared/check_rar.js` parses and normalizes the request, checks registered types and client permission, then invokes the type's validator.
+- `lib/shared/check_resource.js` requires a supplied/defaulted resource for these RAR requests. This is observed provider policy; do not label it a universal CIBA requirement.
+- `lib/actions/authorization/ciba.js` retains request parameters and creates the asynchronous source. It does not run the authorization-code flow's grant-source RAR policy.
+- `lib/provider.js#backchannelResult` accepts a separate `rar` completion option and stores it on the request. `Grant.addRar` alone does not populate it.
+- `lib/helpers/grant_authorization.js#applyAuthorizationDetails` calls the configured access-token policy when token parameters or the completed source contain details.
+- Introspection has its own policy callback. The fixture permits introspection only to the token's issuing client.
+
+[RFC 9396](https://www.rfc-editor.org/rfc/rfc9396.html) defines authorization_details as an array of typed objects, describes token-request comparison and response/introspection representations, and leaves type semantics to the deployment. It does not provide a universal algorithm for narrowing arbitrary application data. Gem design must distinguish these protocol fields from the reference's CIBA completion API and application policy.
+
+## Implementation progress: storage and structural validation only
+
+The gem now contains `Schema.add_authorization_details`, an explicit additive helper for nullable request `requested_authorization_details`, saved-grant `authorization_details`, issued-token `ciba_authorization_details` and client `authorization_details_types` fields. The table names and request column can be overridden. It does not backfill consent, run automatically or enable RAR endpoints.
+
+`Rodauth::CibaSupport::AuthorizationDetails.parse` is an internal structural validator (explicit require `rodauth/ciba/authorization_details`). It accepts bounded UTF-8 JSON arrays of typed objects and validates the common array/identifier fields. Limits are 8,192 bytes, 32 entries and JSON nesting depth 10. Returned arrays, hashes and strings are frozen recursively. Unknown type-specific fields are preserved; no authorization or narrowing semantics are inferred.
+
+Duplicate keys are rejected at all depths using JSON's native `allow_duplicate_key: false`. This is a deliberate stricter input boundary than the reference's ordinary JSON.parse. A custom object-class experiment failed to detect duplicates consistently across JSON versions and was removed. JSON >=2.18,<3 is now an explicit runtime dependency; the lockfile selects 2.18.0. Invalid UTF-8 is checked on the byte sequence, including binary-encoded Ruby strings.
+
+Tests in `test/ciba_authorization_details_test.rb` cover duplicate keys, malformed common fields, byte/count/depth limits, encoding, deep immutability and preservation of existing DB rows. This foundation alone does **not** implement request acceptance or authorization. The subsequent optional feature adds those integration paths with mandatory application policies; do not activate it based only on a successful migration.
+
+## Integration requirements and original proposal
+
+Use an opt-in capability and explicit additive migration. Preserve three distinct JSON values: original requested details on the CIBA request, approved details on the saved consent, and effective details on the issued OAuth token. Existing rows represent no additional permission. Do not infer approved details from the original request or mutate already-issued permissions when a saved grant changes.
+
+Keep the existing saved-grant result API. At completion, bind the approved details to that request with application validation; at issuance, compile effective details from the stored request, saved consent, selected resource and token-time narrowing request. Any configurable policy must operate within that verified account/client/consent context. Fail closed if RAR is enabled without required validation/compilation policy. Do not implement a generic deep-merge or claim JSON equality means authorization.
+
+Required validation includes bounded JSON, array/object/type shape, common field shapes, registered types and per-client allowed types. Type-specific account/operation/amount/target constraints remain application policy. Validate compiled output as well as input. Policy failures during completion or issuance retain the gem's accepted atomic rollback contract.
+
+RAR output belongs in the access token/token response and opaque introspection, not the ID Token. Preserve the resource audience boundary and explicit-claims filtering. Add Discovery and static-client metadata only with implemented enforcement. Reject poll attempts to expand permission; a policy's narrower result must be testable with a concrete type.
+
+Before claiming support: implement the schema/API and client metadata; test missing policy, disabled/mixed-version states, unrequested/unapproved details, request/result snapshot tampering, type/resource/client isolation, hook-time changes, issuance/revocation races, JWT representation and opaque introspection. Add installed-gem smoke coverage. Generic RAR support and the customer's particular support/deletion approval semantics are separate deliverables.

data/docs/research/refresh-reference-contract.md

@@ -0,0 +1,85 @@
+# CIBA refresh token: reference contract
+
+2026-09-30。参照はインストール済み `oidc-provider 9.12.2`。これは仕様全体の適合試験ではなく、既定設定の実測と上流コードの比較である。gem の [refresh 基本実装](../refresh-tokens.md)は開発途中で、公開可能な対応完了ではない。
+
+## HTTP で確認したこと
+
+`test/reference/full-op/lifecycle.mjs` を Node 24.21.0、固定 Docker image、network none で実行した。[実行ログ](../validation/node-refresh-reference.txt)。既存 lifecycle ケースも成功。今回 ping.mjs は再実行していない。
+
+- client が `refresh_token` grant を登録し、CIBA 要求が `offline_access` を含む場合のみ、既定 policy は refresh token を発行する。片方だけの場合は発行しない。
+- 更新で元の scope にない `read` を要求すると `invalid_scope`。
+- `scope=openid` に縮小した更新の次に scope を省略すると、元の `openid offline_access` に戻る。更新時の縮小はそのアクセストークンだけに適用される。
+- 発行直後の confidential client の refresh token は、既定 rotation policy では同じ値で再利用できる。
+- refresh token の保存モデルには元の authTime/acr/amr が残り、更新後 ID Token は元の nonce を持つ。この試験の claim 設定では auth_time/acr/amr は出力されない。保存と claim 出力の条件を混同しない。
+- 保存 Grant を削除すると更新は `invalid_grant` になる。
+- 保存モデルの iat/exp を変更し TTL の80%が経過した fixture では、既定 policy が rotation し、旧 token に consumed、後続 token に同じ grantId と rotations=1 を保存する。実時間で寿命の80%を待った試験ではない。
+- 別の refresh 対応 client が旧 token を使用しても `invalid_grant` で拒否するだけで Grant は残る。正当な client が使用済み token を再利用すると Grant が消え、後続 refresh token は使用不能、後続 access token の introspection は active=false になる。
+- exp を過去にした保存 fixture は `invalid_grant`。その Grant は保持される。memory adapter の期限管理も含むため、expired token が必ず handler の期限分岐まで到達した証拠ではない。
+- resource A/B を要求して A の read token を最初に発行しても、refresh は B の write token を取得できる。resource 省略では OIDC scope に戻り、未要求の宛先は `invalid_target`。
+- 保存 Grant の B/write を後から拒否すると B の refresh は成功するが scope は空になる。初回 token の scope を refresh の元許可として使ってはいけない。
+- revocation の既定 policy は別 confidential client の live token 取消しを400 `invalid_request` で拒否する。正当な client の取消しは空bodyの200で、保存 Grant ごと無効化する。hint の省略・`refresh_token`・`access_token`・未知値で同じ結果。取消し後は別 client の再送も200になる。
+- claims/RAR を伴う rotation は source の claims/rar/authTime を後続に保持する。保存 Grant で後から拒否した email は次の ID Token に含まれない。参照アプリの RAR policy は完了時に明示した source.rar を返し、更新パラメータで read/delete を再要求しても read のまま。RAR policy は固定したテストアプリのものであり、一般的な権限縮小アルゴリズムではない。
+
+## コードから確認した境界
+
+参照側 `lib/helpers/defaults.js` の issueRefreshToken/rotateRefreshToken、`lib/helpers/grant_common.js`、`lib/actions/grants/refresh_token.js` を確認した。
+
+参照側は RefreshToken を AccessToken とは別のモデルとして保存し、元の scope、resource、claims、rar、nonce、認証情報、grantId を保持する。更新では保存 Grant を検証し、resource/scope/承認から新しいアクセストークンを構成する。rotation 後の使用済み token の再利用は関連 Grant の取消しへ進む。上記 HTTP ケースで rotation/replay/resource を確認したが、claims/RAR の refresh 併用は未検証。
+
+rodauth-oauth 1.7.0 の `oauth_base.rb#create_token` は既定で毎回 rotation し、`create_token_from_token` は既存 oauth_grants 行の token と期限を更新する。元の許可を保持する独立した RefreshToken モデルではない。比較開始時の gem は refresh grant を super に渡していた。現在の開発実装は CIBA 専用 namespace の token を別処理し、それ以外を super に渡す。
+
+したがって `generate_token(..., true)` への変更だけでは整合しない。CIBA 元要求の許可と、今回の access token に限定された scope/resource/claims/RAR を分け、保存承認の期限・取消し・account/client を更新でも検証する必要がある。通常の OAuth refresh の既定設定を OP 全体で変更しない。
+
+## 次の実装前に残る検証
+
+- refresh での claims/RAR、rotation 後の認証情報・元許可の保持。
+- gem の更新処理、同時更新・取消し、発行失敗 rollback、機能無効化。保存 migration のみ下記の段階まで実装。
+
+上記のうち更新・rotation/replay・署名失敗 rollback・無効化・同時 rotation は基本実装へ接続した。refresh token を提示する取消し endpoint、期限切れ cleanup、更新 hooks/events も接続した。claims/RAR の opaque/JWT 更新は元の要求・現在の承認・アプリ policy の分離を試験した。access token を提示する grant-wide 取消し、Ruby matrix・配布 gem での検証は残る。
+
+## 保存基盤の実装段階
+
+`Schema.create_refresh_tokens(db, ...)` を追加した。明示的な追加 migration であり、呼び出しても refresh の受付・発行は有効にならない。まだ導入用の機能として公開する段階ではない。
+
+- `token_digest` の一意制約と `consumed_at` によって、rotation 後も旧 token の使用済み記録を保持できる。生の refresh token 用の列は持たない。
+- 元の account/client、保存承認への外部キー、scope、要求した claims/resources/RAR、認証時刻・acr/amr・nonce を、access token の絞り込まれた属性と別に保存する。
+- 初回作成時刻・今回発行時刻・期限・rotation 回数を持ち、node の経過時間による rotation を実装するための情報を保持する。lock_version は既存の CIBA と同様に DB の競合制御に使用する予定。
+- 要求テーブルへの外部キーを持たず、短寿命の要求を cleanup しても refresh source は残る。保存承認・account/client の削除時は cascade する。承認の論理取消しは更新処理で検証する必要があり、この migration だけでは強制されない。
+
+保存テストは既存要求・発行 token・承認の保持、digest 重複拒否、使用済みと後続 token の共存、要求削除後の保持、承認削除時の cascade、transaction rollback、テーブル名変更を対象とする。この段階の後、基本プロトコル処理と replay 取消しを実装した。
+
+Ruby 4.0.6 の SQLite/PostgreSQL/MySQL で各 **2 tests / 17 assertions** 成功。[限定 matrix のログ](../validation/refresh-storage-matrix.txt)。これは追加 storage テストのみの実行であり、既存全 suite の再実行や Ruby 3.3/3.4 の確認ではない。
+
+基本 runtime 接続後、同じ3 DBで全 suite 各 **190 tests** 成功（SQLite 1709 assertions、PostgreSQL/MySQL 1706）。[runtime matrix](../validation/refresh-runtime-matrix.txt)。同時 rotation、通常 OAuth refresh の維持、client 登録削除、認証情報・scope 保持、resource の宛先変更を含む。auth_time は既存 completion API と同じく省略可能なので nullable に修正した。Ruby 3.3/3.4・配布成果物での refresh 検証はまだ行っていない。
+
+refresh の revocation 接続後は3 DBで各192 tests成功（1756〜1759 assertions）。その後の取消し済み token の扱いの調整は、3 DB各2 tests/54 assertionsで確認した。[全体](../validation/refresh-revocation-matrix.txt)、[最終差分](../validation/refresh-revocation-final.txt)。上流の browser session 分岐をこの名前空間の取消しだけで使わず、client 認証に固定した。通常 OAuth token の取消し経路は変更していない。
+
+claims/RAR の opaque/JWT rotation と cleanup 追加後は3 DB各 **195 tests** 成功（1831〜1834 assertions）。[ログ](../validation/refresh-permissions-matrix.txt)。未承認操作の追加拒否、rotation rollback、現在の claim 拒否、後続 source の保持、RAR 無効化、許可縮小、期限境界・外側 rollback を含む。汎用 RAR 意味論や全 callback の組合せを網羅するものではない。
+
+更新フック追加後は3 DBと Ruby3.3/3.4 SQLite の5環境で各 **200 tests** 成功（1894〜1897 assertions）。[DB](../validation/refresh-hooks-matrix.txt)、[Ruby](../validation/refresh-ruby-matrix.txt)。フック後の再検証、rollback、同一 source の再入拒否、outer commit 後の観測と失敗の分離を確認。残件のうち Ruby matrix は解消したが、配布 gem での refresh と access-token 取消しの整合化は未完了。
+
+その後、配布 gem の opaque/JWT refresh smoke を追加して成功した。[ログ](../validation/refresh-package.txt)。CIBA の signed request・claims/resource/RAR と組み合わせ、rotation・認証情報保持・取消し・cleanup を検証した。Discovery の revocation URL 欠落も修正した。配布検証の残件は解消したが、access-token を提示した grant-wide 取消しの整合化は残る。
+
+## JWT client assertion audience
+
+A separate complete-OP fixture now exercises both `private_key_jwt` (RS256) and
+`client_secret_jwt` (HS256), with a fresh signed client assertion at each CIBA
+initiation, token collection and refresh. Node 9.12.2 accepts the issuer as aud
+at all three stages. Wrong audiences and reuse of the same assertion fail client
+authentication. [Reference run](../validation/node-assertion-refresh.txt),
+[harness](../../test/reference/full-op/assertion-refresh.mjs).
+
+The gem originally accepted issuer aud for initiation/collection but rejected
+it for CIBA refresh with HTTP401. Both authentication methods reproduced the
+failure. The corrected audience rule includes the issuer for CIBA refresh only,
+selected by the existing reserved `ciba_rt_` namespace; it does not grant access
+without client signature/secret, replay checks and refresh ownership/consent
+validation. Unrelated authorization-code requests retain the previous audience
+rule. Wrong-audience attempts preserve refresh rows, and assertion replay after
+one successful refresh cannot issue another token.
+[Before correction](../validation/assertion-refresh-red.txt),
+[local regressions](../validation/assertion-refresh-current.txt).
+
+This proves these two authentication methods with issuer aud and the fixture's
+algorithms. It is not mTLS support or coverage of every authentication method,
+JWT algorithm, key rotation or remote-key refresh failure.