rodauth-ciba 0.1.0

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

@@ -0,0 +1,449 @@
+# CIBA mutual TLS: measured reference and unresolved Ruby integration
+
+> 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.
+
+
+## Real TLS reference
+
+Node-oidc-provider 9.12.2 is configured with both `tls_client_auth` and
+`self_signed_tls_client_auth`, certificate-bound access tokens, CIBA poll,
+refresh and introspection. Its TLS listener requests a client certificate.
+Application callbacks obtain the certificate from the TLS socket, use the
+socket's chain-verification result for PKI clients, and compare the subject DN.
+No HTTP header supplies certificate identity. The client also verifies the local
+server certificate. The temporary self-signed test certificates are not
+production credentials. The in-memory adapter and development OP signing keys
+are used; protocol handlers, TLS and cryptography are not stubbed.
+
+Run with the installed reference dependencies and Ruby/OpenSSL/Docker:
+
+```sh
+mise exec ruby -- sh bin/test-mtls-reference
+```
+
+The runner creates and removes temporary certificates. It uses the pinned Node
+image with no external network. [Harness](../../test/reference/full-op/mtls.mjs),
+[certificate generator](../../test/reference/full-op/mtls-certificates.rb),
+[reference log](../validation/node-mtls-reference.txt).
+
+Measured outcomes for both client authentication methods:
+
+- CIBA initiation, approved token collection and confidential refresh succeed
+  with the registered certificate.
+- Missing certificates fail client authentication. Supplying certificate/verify
+  HTTP headers without a TLS certificate also fails.
+- Introspection reports `cnf["x5t#S256"]` equal to base64url SHA256 of the **entire
+  certificate DER**, not the JWK thumbprint of its public key.
+- UserInfo requires the bound certificate. A different certificate with the
+  same public key is insufficient. Matching certificate returns the customer.
+- Self-signed client authentication likewise rejects a distinct certificate
+  with the same public key; registered x5c identifies the certificate.
+
+This fixture covers a DN-based PKI callback and static x5c registration. It does
+not cover every SAN policy, remote JWKS rotation, dynamic registration, proxy
+deployment or multi-process replay/lifecycle behavior.
+
+## Upstream Ruby characterization: not a passing support claim
+
+The historical `test/reference/upstream_mtls_probe.rb` ran the actual
+gem Rack stack with upstream `oauth_tls_client_auth` enabled. Rack server
+variables model a verified TLS peer; unlike the node fixture this probe does not
+perform a TLS handshake. It is deliberately outside the normal regression
+suite and records current defects rather than codifying them as desired behavior.
+[Observed log](../validation/upstream-mtls-probe.txt).
+
+- PKI CIBA initiation/issuance succeeds with matching DN and `SSL_CLIENT_VERIFY`.
+- The stored certificate thumbprint is **not** SHA256 of certificate DER.
+  Source inspection shows upstream hashes the public JWK instead.
+- The resulting bound token accesses UserInfo with no certificate (HTTP200).
+  Upstream's UserInfo path does not enforce the certificate binding here.
+- Header-only `HTTP_X_SSL_CLIENT_CERT` plus `HTTP_X_SSL_CLIENT_VERIFY=SUCCESS`
+  is accepted. This is safe only under an explicit trusted TLS terminator that
+  removes/replaces client-supplied headers; there is no such trust configuration
+  in this probe. It is not evidence that every deployment is exposed.
+- A registered self-signed x5c client returns HTTP500. Upstream's JWKS iteration
+  and comparison use incompatible shapes/values for this registration.
+
+## Required correction boundary
+
+Do not advertise CIBA mTLS support based on enabling the upstream feature alone.
+The default gem configuration does not enable mTLS. Implement an explicit trusted
+certificate/verification boundary for CIBA, correct full-certificate identity
+and digest handling, and connect binding enforcement to the actual UserInfo
+entry point, refresh and introspection. Keep other OAuth grant behavior separate.
+Preserve the distinction between PKI chain/subject validation and registered
+self-signed certificate matching. Then replace characterization expectations
+with rejection/positive regression tests and real TLS installed-artifact checks.
+The initial correction below implements part of this boundary; integration work remains.
+
+## Initial CIBA correction
+
+The extension now requires an explicit `ciba_tls_client_certificate` callback
+when upstream `oauth_tls_client_auth` is enabled, plus the configured grant
+certificate-thumbprint column. The callback returns the TLS peer certificate as
+an OpenSSL certificate or PEM String, or nil. It must derive that value from a
+trusted server/terminator integration that already proved possession of the
+certificate key. No forwarded certificate or verification header is read by the
+CIBA path. Other OAuth routes retain upstream behavior.
+
+For PKI authentication, configure `ciba_tls_client_certificate_authorized?` and
+`ciba_tls_client_certificate_subject_matches?(property, expected)`. Both default
+to false. The first reports actual chain verification; the second checks the
+single registered DN/SAN value. These are application-owned TLS integration
+policies like the reference callbacks. Multiple registered identity properties
+or mixed TLS authentication method lists are rejected. For self-signed clients,
+the first x5c certificate of a registered key must match the full peer certificate
+DER digest; a same-key/different-certificate presentation fails. Remote JWKS uses
+the existing guarded HTTP path, but TLS-specific remote rotation remains untested.
+
+Certificate-bound CIBA issuance now stores SHA256(DER) and exposes it in signed
+JWT cnf and opaque introspection. UserInfo verifies the live saved issuance and
+requires the matching certificate. Confidential refresh authenticates again and
+binds the new access token; it does not add public-client refresh-token binding.
+A missing required certificate or simultaneous DPoP binding is rejected before
+upstream's nested persistence transaction. Rejecting the combination later had
+consumed approval; validation was moved before proof reservation/persistence and
+the regression now verifies unchanged approval and zero token/proof rows.
+
+The old upstream-only characterization probe has been replaced by
+`test/ciba_mtls_test.rb`; its historical output above is retained as failure
+evidence, not current behavior. The new tests cover both authentication methods
+and opaque/JWT tokens, default/header-only rejection, wrong certificate, wrong
+PKI authorization/subject, configuration checks, issuance-signing rollback,
+UserInfo expiry/revocation, introspection, refresh and DPoP coexistence rejection.
+[Local regression run](../validation/ciba-mtls-current.txt).
+
+This is not complete mTLS alignment. DCR metadata/management,
+remote certificate-key rotation, all SAN
+callback policies, aliases/discovery and additional client-method combinations
+still need work. The reference real-TLS fixture does not prove the new Ruby
+callbacks are correctly wired in a deployment.
+
+## Installed gem with a Ruby TLS server
+
+`bin/verify-package` now runs the packaged `examples/mtls_smoke.rb` from its
+temporary gem installation. It checks the loaded mTLS module's filesystem path
+against that installation. A WEBrick TLS listener invokes the actual Rack app;
+the requests are sent over HTTPS with Net::HTTP, not Rack mock dispatch. Rack's
+environment helper is used only to adapt the incoming HTTP request. The trusted
+certificate value is assigned from WEBrick's TLS peer certificate after all
+HTTP headers have been mapped, so caller headers cannot populate that value.
+
+The listener requests peer certificates and allows self-signed chains to reach
+the application, like the node fixture. For PKI authentication the application
+callback independently verifies the peer against the test trust store and
+checks the registered DN. A foreign certificate with the same DN fails that
+verification. Self-signed authentication matches registered x5c. The HTTP client
+verifies the server's certificate and hostname against a separate local trust
+store. Keys and certificates are generated in memory for each run.
+
+All four combinations (PKI/self-signed, opaque/JWT) pass CIBA initiation,
+approved token collection, UserInfo and confidential refresh. Absent certificates
+and forwarded-header-only certificate claims fail authentication; missing and
+same-key/different certificates cannot use bound UserInfo tokens. A new access
+token after refresh still requires its certificate. ID Token signatures,
+issuer/audience and customer subject are checked; JWT access-token cnf and opaque
+introspection cnf match SHA256 of the certificate DER.
+[Installed TLS run](../validation/mtls-installed-tls.txt).
+
+This verifies one in-process Ruby TLS adapter and application trust policy with
+static client registration on SQLite/Ruby4.0.6. It does not cover a production
+reverse proxy, intermediate-chain policies, all SAN policies, dynamic certificate
+registration/rotation or multiple application processes. No gem is published and
+no network dependency resolution is performed by this verification.
+
+## Dynamic registration and management
+
+The CIBA metadata allowlist now includes the five PKI subject properties and
+`tls_client_certificate_bound_access_tokens`. When the TLS feature is enabled,
+binding accepts only JSON booleans and defaults to false. Explicit properties
+require their configured storage columns; missing storage fails registration.
+PKI clients must supply exactly one nonempty string subject DN/SAN property.
+Other authentication methods discard subject properties, as the reference does.
+Self-signed clients require registered `jwks` or `jwks_uri`. Requiring both DPoP
+and TLS token binding fails registration. With TLS disabled, TLS properties are
+ignored instead of passed through as arbitrary DB fields.
+
+Full management replacement resets omitted binding to false and preserves false
+in its response. Invalid updates preserve the saved row and the management
+credential. Changing issuance policy does not remove existing access-token
+binding: the gem regression dynamically registers a self-signed client, issues a
+bound token, disables future binding through management, and verifies certificate
+requirements on the old token while the new token is unbound.
+[Local cases](../validation/mtls-registration-current.txt).
+
+The real-TLS node harness now obtains its PKI and self-signed clients through
+authenticated DCR and uses the generated client IDs for the complete CIBA flow.
+It measures boolean validation, one-subject validation, required self-signed keys,
+default false, incompatible dual binding and failed/successful management
+replacement. [Reference run](../validation/node-mtls-registration.txt).
+
+The static-registration installed-gem evidence above is historical; the fixture
+now uses DCR as described below. Remote certificate rotation,
+all SAN callback semantics and aliases remain to be aligned. The global binding
+policy/capability distinction is addressed below.
+
+## Installed DCR and management over TLS
+
+The packaged TLS fixture now creates both PKI and self-signed clients through the
+actual authenticated registration endpoint. It uses the returned client ID for
+initiation, token collection, introspection and refresh, and checks that ID Token
+audience matches that generated ID. All existing TLS certificate rejection and
+opaque/JWT binding checks still run in all four combinations.
+
+An invalid management PUT leaves policy and the credential usable. A successful
+full replacement omitting the binding flag returns false and rotates the
+management credential: the old credential is rejected and the new one can read
+the client. Old access tokens still require their original certificate. A later
+refresh authenticates through mTLS but, under the new policy, issues an unbound
+access token which can use UserInfo without a certificate. This distinguishes
+TLS client authentication from access-token certificate binding.
+
+[Installed DCR TLS run](../validation/mtls-dcr-installed-tls.txt). This is the
+temporarily installed artifact on Ruby4.0.6/SQLite using the same explicit TLS
+trust boundary described above. It does not prove certificate rotation or
+arbitrary deployment/trust-policy behavior. Existing package smoke checks also
+pass; no production code changed in this verification increment.
+
+
+## Capability versus client binding policy
+
+The node TLS harness advertises binding capability true while a client with
+binding false obtains unbound new access tokens. Existing bound tokens still
+require their certificate. This is measured after management replacement and
+refresh, not inferred from metadata alone.
+[Reference run](../validation/node-mtls-capability.txt).
+
+The gem previously let upstream's global binding flag override a CIBA client's
+false policy; both opaque and JWT regressions reproduced it.
+[Failing cases](../validation/mtls-capability-red.txt). CIBA issuance and refresh
+now use only client binding metadata. The upstream global setting is not mutated
+and its ordinary OAuth grant handling remains delegated to upstream. Enabling
+`oauth_tls_client_auth` advertises capability true in both metadata documents,
+regardless of that global policy. A prepended metadata method avoids feature
+load order overwriting the value; the OIDC allowlist preserves it.
+
+The related mTLS/Discovery suite passes **21 tests / 311 assertions** on each of
+SQLite, PostgreSQL and MySQL, with no failures/errors/skips.
+[Matrix](../validation/mtls-capability-matrix.txt). The installed TLS fixture now
+sets upstream's global policy true and still verifies management replacement to
+false, certificate-free use of new refreshed tokens, and certificate enforcement
+on old tokens in all four PKI/self-signed × opaque/JWT combinations.
+[Package](../validation/mtls-capability-package.txt). This does not establish
+identical configuration APIs, remote rotation, endpoint aliases or arbitrary
+proxy/SAN policy equivalence.
+
+
+## Endpoint aliases are application deployment configuration
+
+Inspection of the pinned node9.12.2 `lib/actions/discovery.js` finds no automatic
+`mtls_endpoint_aliases` generation. The real TLS fixture now first verifies that
+absence, then adds aliases through application middleware and serves the same
+provider on a second HTTPS port. Discovered aliases for backchannel authentication,
+token, introspection and UserInfo are used in the complete existing CIBA flow.
+Canonical endpoint metadata and issuer remain unchanged; ID Token issuer remains
+canonical too. [Reference run](../validation/node-mtls-aliases.txt).
+
+The installed gem fixture follows the same deployment boundary: application
+Discovery middleware publishes the four aliases and two WEBrick TLS listeners
+serve the same Rack application. `base_url` and `authorization_server_url` remain
+pinned to the canonical issuer. Request environments use the actual listener
+origin, while the peer certificate comes from the TLS socket. The client follows
+the discovered alias URLs; absent/header-only/foreign certificates still fail,
+UserInfo still checks certificate binding, and management still changes only
+future issuance policy. The ID Token signature, issuer and audience are verified.
+All PKI/self-signed × opaque/JWT combinations pass.
+[Installed package](../validation/mtls-aliases-package.txt).
+
+No gem routing API is needed for this measured deployment. Aliases are not
+created automatically and the application owns both published URLs and actual
+TLS routing. This is evidence for distinct ports and unchanged paths, not for
+arbitrary path rewrites, reverse proxies, alias-only access enforcement, DPoP
+proof URLs on aliases, or certificate rotation. Earlier references to aliases as
+an unimplemented parity feature were too broad: automatic alias routing is not a
+behavior of the pinned reference. Deployment-specific cases remain unverified.
+
+
+## Remote x5c rotation and retrieval failures
+
+The node TLS fixture now registers a self-signed client with a remote `jwks_uri`.
+Its locally owned HTTP JWKS receiver is explicitly allowed through the provider's
+fetch policy; inbound authentication still uses real TLS peer certificates.
+Both reference and gem tests verify: a cache with `max-age=3600` retains the old
+certificate; a new certificate with the same public key does not force a fetch;
+after forced cache expiry, only the newly published certificate authenticates.
+Tests expire the actual cache directly rather than waiting an hour. This proves
+replacement semantics, not a wall-clock TTL or distributed-cache guarantee.
+[Reference run](../validation/node-mtls-remote.txt).
+
+The gem had reused the signed-request key-lookup flag during TLS authentication.
+A remote 503 therefore returned `invalid_request`, incorrectly treating this as
+key lookup after successful client authentication. A distinct TLS lookup flag
+now selects guarded HTTP transport and returns `invalid_client_metadata` for
+retrieval/JSON/structure failure, matching the observed reference response.
+An empty key set is structurally valid but cannot authenticate, so returns
+`invalid_client` with401. Failed requests do not create pending CIBA requests.
+[Regression before fix](../validation/mtls-remote-red.txt).
+
+There is a deliberate failure-cache difference: after refreshing a populated
+reference key store fails with503, its new freshness timestamp retains old keys
+and the next authentication can succeed without another fetch. The gem does not
+restore an expired cached key set after failure and continues to reject until a
+successful fetch. This stricter behavior is retained rather than copying stale
+credential acceptance. Neither behavior instantly revokes already cached keys;
+rotation/revocation must account for the configured cache lifetime. Node also
+uses a minimum60-second freshness interval; the gem retains upstream's HTTP
+cache policy, including `no-cache`, without claiming identical TTL behavior.
+
+The final gem case checks repeated503 rejection, blocked destinations without
+network requests, absence of pending records on failure and successful recovery.
+[Final three-DB case](../validation/mtls-remote-final.txt). The broader mTLS/remote
+JWKS subset passes17 tests /304 assertions per DB before those final additions.
+[Related cases](../validation/mtls-remote-matrix.txt).
+
+This increment does not yet exercise remote certificate rotation in the
+installed artifact, simultaneous issuer processes, or a real HTTPS JWKS rotation
+receiver. The installed package's existing TLS/aliases and other smoke flows
+are separately rerun; outbound TLS transport has separate earlier JWKS evidence.
+
+
+## Installed HTTPS certificate rotation and JWT introspection
+
+The installed mTLS smoke now runs in a child process whose `SSL_CERT_FILE` trusts
+only the locally generated fixture certificate file in addition to the process's
+normal trust-path behavior. Verification is never disabled. This isolates the
+fixture CA from the parent process and later smoke fixtures. Self-signed clients
+use a dynamically registered HTTPS `jwks_uri`; the real outbound transport reads
+`x5c` from the owned receiver, with only loopback explicitly allowed by the app.
+
+Both opaque and JWT flows pass remote cache reuse and certificate mismatch
+without refetch. After publishing a different certificate containing the same
+key and explicitly expiring the cache, the old certificate cannot authenticate,
+while the new one can refresh an existing confidential client's token. The new
+access token's UserInfo and introspection binding refer to the new certificate.
+Previously issued tokens still require the original certificate. Repeated503
+responses produce invalid_client_metadata without adding pending requests;
+restoring the receiver allows authentication again.
+
+The expanded fixture exposed a runtime defect: JWT introspection discarded cnf
+because the upstream serializer receives verified claims rather than a grant
+row. The mTLS serializer now resolves the live CIBA issuance, checks client and
+subject provenance plus the saved/claimed certificate digest, then includes
+`cnf.x5t#S256`. Expired or revoked issuance returns inactive. This is scoped to
+CIBA tokens with the TLS feature; unrelated JWT handling stays upstream-owned.
+[Failing installed run](../validation/mtls-remote-installed-tls.txt).
+
+The corrected package passes the entire installed smoke suite, including both
+remote-rotation variants. [Final package](../validation/mtls-remote-installed-final.txt).
+The mTLS subset passes **14 tests /307 assertions** on each of SQLite, PostgreSQL
+and MySQL, including opaque/JWT introspection cnf, expiry and revocation.
+[DB regression](../validation/mtls-jwt-introspection-matrix.txt).
+
+These tests use forced cache expiry and one application process on Ruby4.0.6;
+they do not establish real-time TTL behavior, distributed invalidation, arbitrary
+proxy trust configuration, or all TLS subject-matching application policies.
+
+
+## Pairwise self-signed TLS client authentication
+
+The reference TLS harness dynamically registers a pairwise self-signed client
+with remote jwks_uri and verifies CIBA issuance and matching UserInfo subject.
+[Reference](../validation/node-pairwise-mtls.txt). The gem's private_key_jwt-only
+pairwise gate rejected this combination ([regression](../validation/pairwise-mtls-red.txt)).
+It now accepts self_signed_tls_client_auth when the TLS feature is enabled,
+while still requiring remote JWKS and rejecting simultaneous inline keys. Actual
+certificate verification remains in the mTLS authentication boundary.
+
+The new gem cases cover opaque/JWT initiation, different-certificate refusal,
+approval, pairwise subject snapshot, canonical stored account, UserInfo and
+refresh. The installed fixture now combines DCR, pairwise self-signed clients,
+HTTPS x5c rotation and mTLS aliases. It exposed a JWT introspection failure:
+upstream tried to look up the pairwise subject as a local account identifier.
+The mTLS serializer now supplies the already-validated issuance's internal
+account ID to that lookup while keeping the public pairwise sub in the response.
+[Local failure](../validation/pairwise-mtls-introspection-red.txt),
+[initial installed failure](../validation/pairwise-mtls-package.txt).
+
+The initial related matrix passes30 tests on each DB; final focused and installed
+results are recorded separately after the introspection correction.
+[Related](../validation/pairwise-mtls-matrix.txt),
+[final DB](../validation/pairwise-mtls-final.txt),
+[final package](../validation/pairwise-mtls-package-final.txt).
+Signed-request-only proof of remote-key ownership remains a separate missing
+pairwise path. These checks do not establish arbitrary app identifier policy or
+multi-process key/sector rotation.
+
+
+The installed pairwise JWT also exceeded Rodauth's default1024-byte parameter
+limit. Its introspection token became empty before CIBA client-auth selection.
+CIBA introspection now permits identified CIBA token input up to8192 bytes;
+other parameters/routes and unrelated tokens retain upstream limits. This
+unverified marker selects parsing/authentication handling only; signature and
+live issuance validation still precede an active response. The final focused
+case uses a254-character pairwise subject and asserts the JWT exceeds1024 bytes.
+The final installed run passes remote certificate rotation and introspection
+with the pairwise subject; no debug tracing remains in the fixture.
+
+### Long JWT introspection security regression
+
+The pairwise mTLS JWT fixture now rejects four otherwise plausible token inputs:
+a foreign signing key, an unsigned JWT, an OP-signed changed subject, and an
+OP-signed unknown CIBA issuance identifier. Each authenticated introspection
+returns active=false. Missing and foreign caller certificates return 401 even
+for the valid long token. These checks exercise actual HTTP routes and the
+stored issuance boundary, not only JWT decoding.
+
+A separate request-parameter check confirms that the CIBA marker only permits
+up to 8192 bytes at introspection's token parameter. An 8193-byte candidate,
+a non-CIBA 1025-byte string, the token parameter at another route, and an
+oversized client_secret still yield no parameter value. The fabricated marker
+in this parser test is not authenticated; the route tests above establish that
+selecting the larger parsing limit does not authorize a token or caller.
+
+[Local regression](../validation/pairwise-mtls-introspection-security.txt):
+3 tests, 45 assertions, no failures/errors/skips. No runtime change was needed.
+This is not a new three-database or full-suite execution.
+
+## Real TLS aliases with certificate authentication and DPoP tokens
+
+The previously unverified combination now has a complete real-TLS flow in the
+pinned reference OP and installed gem. A separate registered client uses either
+`tls_client_auth` or `self_signed_tls_client_auth`, requires DPoP-bound access
+tokens, and explicitly does not require certificate-bound access tokens.
+These are separate responsibilities: the certificate authenticates the client;
+the DPoP key constrains access-token use.
+
+Both fixtures discover application-owned aliases on a second TLS listener while
+retaining the canonical issuer. They verify:
+
+- initiation, approval and token collection through the alias;
+- rejection of missing client certificates and missing DPoP proofs at collection;
+- rejection of a proof whose htu names the canonical endpoint instead of the alias;
+- signed ID Tokens with canonical issuer/client audience and no inherited cnf;
+- introspection returning exactly the DPoP jkt, with no x5t#S256 binding;
+- UserInfo rejecting a Bearer request even with the certificate, and accepting a
+  DPoP proof without a client certificate;
+- refresh requiring both client certificate authentication and DPoP, and retaining
+  the exact expected DPoP-key confirmation in the new access token.
+
+The gem fixture additionally runs both opaque and JWT access-token modes and keeps
+upstream's global certificate-binding setting enabled, proving the explicit CIBA
+client binding policy remains authoritative. Its four combinations use actual
+WEBrick TLS peer certificates and trusted server certificates, not forwarded
+certificate assertions. UserInfo uses GET in this integration fixture.
+
+[Reference execution](../validation/node-mtls-dpop-alias.txt),
+[installed gem execution](../validation/mtls-dpop-alias-installed.txt).
+No runtime change was needed after the earlier DPoP endpoint-URI correction.
+This closes the concrete combined-alias coverage gap. Production reverse proxies,
+cluster nonce/key distribution and arbitrary application trust policies are not
+established by this local integration test.

data/docs/research/node-ciba-lifecycle.md

@@ -0,0 +1,30 @@
+# CIBA lifecycle comparison against node-oidc-provider v9.12.2
+
+2026-09-30. GitHub connector retrieval succeeded after shell DNS and Web cache failures. The earlier source-access limitation is resolved for the start route, grant handler and request model. The initial analysis below used source inspection and an isolated harness; a subsequent [complete HTTP OP test](../../test/reference/full-op/README.md) now verifies the listed lifecycle scenarios with actual signing and the built-in memory adapter on Node24 LTS.
+
+The unchanged CIBA handler and source helper now also execute in [an isolated reference harness](../../test/reference/README.md). `node --experimental-vm-modules test/reference/lifecycle.mjs` passes on Node v26.5.0; [log](../validation/node-reference-lifecycle.txt). With non-transactional in-memory persistence, issuance failure leaves consumption intact and the next poll revokes the Grant and returns invalid_grant. Cryptography, actual token persistence and global HTTP middleware are stubbed/absent. This confirms local control-flow behavior only.
+
+## Confirmed ordering
+
+- [Start route](https://github.com/panva/node-oidc-provider/blob/v9.12.2/lib/actions/authorization/ciba.js): save the BackchannelAuthenticationRequest, prepare auth_req_id/expires_in, await triggerAuthenticationDevice. There is no compensating deletion in this function if the trigger throws. The gem now uses the same persistence-before-trigger boundary; application-owned outer transactions remain a Sequel-specific concern.
+- [CIBA grant handler](https://github.com/panva/node-oidc-provider/blob/v9.12.2/lib/actions/grants/ciba.js): find a client-bound request; check expiry; return authorization_pending when neither grant nor error exists; consume; propagate a saved result error; validate the Grant; issue tokens.
+- [Source helper](https://github.com/panva/node-oidc-provider/blob/v9.12.2/lib/helpers/grant_source.js): consuming an already consumed source revokes its Grant and throws invalid_grant. Grant lookup checks existence, expiry and client identity.
+- [Request model](https://github.com/panva/node-oidc-provider/blob/v9.12.2/lib/models/backchannel_authentication_request.js): consume invokes adapter.consume and emits consumed. No consumable mixin is needed for this model; the previously guessed mixin path returned 404.
+- [Common issuance](https://github.com/panva/node-oidc-provider/blob/v9.12.2/lib/helpers/grant_common.js): validates the account and Grant/account match, saves the access token, optionally saves a refresh token, then generates the ID Token and response.
+
+## Implemented alignment
+
+The gem now checks request expiry before consumed status. Replaying an unexpired consumed approved request revokes its saved CIBA consent and linked OAuth token rows, then returns invalid_grant. A denied result is consumed on first collection (access_denied); a second collection returns invalid_grant. Trusted Ruby completion retries remain idempotent and do not themselves replay token collection.
+
+Tests: test_replayed_result_revokes_its_saved_consent_and_tokens, test_denied_result_is_consumed_on_first_collection, test_expiry_precedes_consumed_result_check.
+
+Revocation is scoped by the saved consent ID: reusing one consent across multiple requests means replay can revoke all tokens linked to that consent. Offline JWT verification cannot observe a database revocation without an application/resource-server mechanism.
+
+## Deliberate differences and remaining gaps
+
+- The node start function omits interval and the CIBA grant handler has no slow_down branch. The gem advertises and enforces an increasing interval. This statement is limited to these functions; it does not prove absence of all application/server rate limiting.
+- node consumes before result-error propagation and token generation. The gem deliberately rolls back consumption and token rows if issuance/signing fails, per [ADR 0004](../adr/0004-retain-atomic-issuance-and-stage-alignment.md). Atomicity of an application's node adapter is not established by reading these functions.
+- node accepts all three hint mechanisms and invokes application user-code validation. Initial gem scope remains login_hint only; broader capabilities are tracked in the accepted [staged roadmap](../alignment-roadmap.md).
+- node persists claims, nonce, resource, params and RAR-related state. The gem now persists nonce and optionally requested/approved/rejected claims. Full claims constraint policy, resource and RAR remain gaps.
+- node propagates OIDC result errors; the gem now supports generic error codes with one-use collection and explicit storage migration (see completion-error-boundaries.md).
+- Complete node HTTP lifecycle scenarios and the gem's SQLite/PostgreSQL/MySQL matrix now pass. Production node adapters, process crashes and application-specific response-loss recovery remain unverified.

data/docs/research/node-oidc-provider-comparison.md

@@ -0,0 +1,45 @@
+# node-oidc-provider と rodauth-ciba の比較
+
+後続調査で専用ソースをGitHub connectorから取得できた。最新の処理順序・差分は[ライフサイクル比較](node-ciba-lifecycle.md)を参照。以下は取得前の比較記録。
+
+調査日: 2026-09-30。この比較は整合化作業前のスナップショット。以後の変更は[整合化作業](../node-alignment.md)を参照。結論: アプリが本人確認と承認UIを担当し、内部APIでOPへ結果を渡す分担は共通。node側は既存OIDCの認可モデル・拡張機能を広く利用し、gem側はpoll/login_hintと同一DB内の状態遷移に範囲を絞っている。機能数だけでは適合性・安全性を比較できない。
+
+比較対象は公開時点でlatestと表示された [node-oidc-provider v9.12.2](https://github.com/panva/node-oidc-provider/releases/tag/v9.12.2) と、この作業ツリーのrodauth-ciba 0.1.0。`lib/rodauth/features/ciba.rb` のSHA-256は `f4336c948a135f3682d08eb292408eaaa168edfff13f8702a21c7af46e3d2121`。
+
+これはソース・設定・APIの比較であり、相互接続試験ではない。shellからGitHubをcloneできず、Web経由で取得できたタグ固定の一次資料を読んだ。v9.12.2の `actions/authorization/ciba.js` と `actions/grants/ciba.js` は取得できていない。mainのgrantファイルも参照したが、タグとの差を保証できないため、そこだけからv9.12.2の挙動を断定しない。特にhint全種の検証詳細、slow_down、発行失敗後の再試行、JWT認証の全負例は今回の比較では未確定。
+
+| 観点 | node-oidc-provider | このgem | 判断 |
+|---|---|---|---|
+| 配送 | poll / ping。既定poll、pushは設定検証で拒否 | pollのみ | poll初版を維持してよい。[設定検証](https://github.com/panva/node-oidc-provider/blob/v9.12.2/lib/helpers/configuration.js#L607) |
+| アプリとの境界 | `triggerAuthenticationDevice` と `backchannelResult` | `ciba_request_accepted` と `approve_ciba_request` / `deny_ciba_request` | 内部APIという方向は共通。どちらも業務用の承認HTTP APIをこの境界で標準化するものではない。[node設定](https://github.com/panva/node-oidc-provider/blob/v9.12.2/lib/helpers/defaults.js#L1116) |
+| 承認結果 | 保存済みGrantまたはエラー。account/client一致を確認 | account一致を確認し、要求を承認/拒否 | nodeのGrantはscope・claim・resourceごとの許可/拒否を表現できる。gemの承認APIにはscopeを減らす引数がない。[結果API](https://github.com/panva/node-oidc-provider/blob/v9.12.2/lib/provider.js#L239)、[Grant](https://github.com/panva/node-oidc-provider/blob/v9.12.2/lib/models/grant.js) |
+| hint / user_code | login_hintとlogin_hint_tokenの解決、user_code検証をアプリ用callbackとして提供 | login_hintのみ解決を差替え可能。他は入口で拒否 | 対応範囲の差。nodeのcallbackもアプリ実装が必要で、任意のトークン形式を自動で検証するわけではない。[callback定義](https://github.com/panva/node-oidc-provider/blob/v9.12.2/lib/helpers/defaults.js#L527) |
+| 署名付き要求 | request-object処理をCIBAにも接続 | 明示的に未対応 | JWTクライアント認証とは別機能。初版へ自動追加しない。[処理スタック](https://github.com/panva/node-oidc-provider/blob/v9.12.2/lib/actions/authorization/index.js#L90) |
+| クライアント登録 / subject | 共通schemaにCIBA metadata・pairwise向け認証条件がある | 静的登録・public subjectのみ。CIBA DCR拒否 | 公開OSSとしての拡張余地だが初期用途の必須条件ではない。[client schema](https://github.com/panva/node-oidc-provider/blob/v9.12.2/lib/helpers/client_schema.js#L133) |
+| Refresh Token | 共通発行処理にRefresh Token生成とpolicy判断がある | offline_accessを除外し、CIBA refreshを発行しない | 長期アクセスが必要になった時点で再検討。nodeの全CIBA設定で必ず発行されるとは言わない。[共通発行処理](https://github.com/panva/node-oidc-provider/blob/v9.12.2/lib/helpers/grant_common.js#L95) |
+| 詳細な認可要求 | CIBA開始スタックにclaims / resource / RARの処理を接続 | CIBA専用処理ではscope等の固定項目を保存 | 業務操作の詳細は現在アプリが保持する必要がある。[処理スタック](https://github.com/panva/node-oidc-provider/blob/v9.12.2/lib/actions/authorization/index.js#L114) |
+| binding_message | 既定は限定文字集合・1〜20文字。検証callbackあり | 制御文字を除くUTF-8、最大128bytes | ライブラリの方針差。nodeの文字数をCoreの必須条件として移植しない。[検証既定値](https://github.com/panva/node-oidc-provider/blob/v9.12.2/lib/helpers/defaults.js#L546) |
+| 永続化 | モデル単位のadapter。既定in-memory、本番用adapterは導入側 | Sequel、既存OAuthと同じDB | gem側のDB選択は単純で妥当。汎用adapterを追加する理由にはならない。[adapter契約](https://github.com/panva/node-oidc-provider/blob/v9.12.2/example/my_adapter.js) |
+| イベント | Provider event emitter。モデル保存後にsaved等をemit | transaction内のbefore/afterと、outer commit後の例外隔離した観測を分離 | nodeのイベントを「DB commit後・失敗しても認証へ無影響」と同一視しない。[保存・emit](https://github.com/panva/node-oidc-provider/blob/v9.12.2/lib/models/base_model.js#L71)、[イベント一覧](https://github.com/panva/node-oidc-provider/blob/v9.12.2/docs/events.md) |
+| 適合性の証拠 | READMEにFAPI CIBA認定を記載 | 宣言した範囲のローカルテスト、認定なし | 実績には差がある。ただしnodeの任意設定が認定済みになるわけではない。[README](https://github.com/panva/node-oidc-provider/blob/v9.12.2/README.md#certification) |
+
+gem側の根拠は [実装](../../lib/rodauth/features/ciba.rb)、[API契約](../api.md)、[テスト対応表](../protocol-coverage.md)、[直近のレビュー結果](../security-review.md)。最後の実行記録はRuby 4.0.6 / SQLiteで76 tests / 563 assertions。今回はコード変更・テスト再実行をしていない。
+
+特に参考になるのは、nodeが「認証要求」と「許可した内容」を別のモデルで扱う点。gemは受付時に許可候補scopeを保存し、承認時には全体を承認する。これは初版の単純な承認には合う。一部承認が必要なら、まず `approved_scopes` 相当の小さなAPIを検討できるが、その際は受付scopeの部分集合・openid維持・保存後の変更禁止・再試行一致・Token応答のscopeを一緒に検証する必要がある。nodeのGrant体系全体の移植は不要。
+
+今回の「誰が、どの顧客の、何の操作を承認したか」には、scopeだけでは足りない。これは両実装の機能数とは別のアプリ設計問題。現行gemの `after_ciba_request` で、内部request IDに紐付く操作対象・実行者・範囲・期限のスナップショットを同じDBへ保存する案が使える。承認画面と実行側が同じ内容を参照し、後から内容を差し替えられないことを確認する。RARを初版へ追加する前に、この既存フックで足りるかを試すのが妥当。
+
+状態遷移は、単にnodeへ揃えるべきではない。nodeの `backchannelResult` はGrantとのclient/account一致を確認して要求を保存するが、読んだメソッド内にはgemと同じ「同一結果なら冪等、異なる結果ならConflict」という分岐はない。一方gemは期限・完了済み状態・認証contextを確認し、行ロックと状態versionで変更を直列化する。node側の全呼出経路・adapterを含めた競合試験はしておらず、これを脆弱性の認定には使わない。[node結果API](https://github.com/panva/node-oidc-provider/blob/v9.12.2/lib/provider.js#L239)
+
+また、nodeの共通消費処理は消費済みsourceを拒否し、関連Grantのrevokeを呼ぶ。adapterにはfind/upsert/consume等の契約があるが、要求消費と複数トークン保存を一つのDB transactionで確定する保証は、この契約だけからは読み取れない。gemはそれを自前でまとめ、署名失敗時のrollbackと再試行をテストしている。nodeより安全という結論ではなく、保証を置く場所が異なるという比較である。[消費処理](https://github.com/panva/node-oidc-provider/blob/v9.12.2/lib/helpers/grant_source.js#L21)、[adapter契約](https://github.com/panva/node-oidc-provider/blob/v9.12.2/example/my_adapter.js#L194)
+
+再利用防止でも、nodeの `ReplayDetection.unique` はfindしてからsaveするモデル。gemはclient IDとjtiの組をhash化してunique insertする。nodeのモデルをそのままコピーして、gemのDB unique制約を弱める理由はない。ただしnodeでの同時リクエストの可否はadapter・呼出経路を含めて未検証。[ReplayDetection](https://github.com/panva/node-oidc-provider/blob/v9.12.2/lib/models/replay_detection.js)
+
+通知失敗の扱いにも注意する。nodeの設定ではAD起動helperを要求受付後・応答前に呼ぶ。gemの受付callbackはcommit後で、例外でも成立済みの受付を変えない。gemでは通知漏れが起きてもpending要求の走査で回復できるが、本番では同一DBへのoutbox保存と配送workerをアプリ側で用意するのが候補になる。観測イベント自体を配送保証とみなさない。pingについてnodeは結果保存後にHTTP通知し、200/204を受理する実装であり、読んだメソッドには永続的な再送queueはない。[ping処理](https://github.com/panva/node-oidc-provider/blob/v9.12.2/lib/models/client.js#L379)
+
+次に行うなら、機能の横並び化より、次の順序を推奨する。
+
+1. 初期アプリで「承認内容の固定」と「通知失敗からの復旧」を既存のtransactional hook・内部IDで確認する。
+2. gemは現行のpoll/login_hint範囲を維持し、未実施のPostgreSQL/MySQL検証を完了する。
+3. nodeを動かせる環境で、同じクライアント要求を両OPに送り、開始・拒否・期限・二重引換え・再送を比較する。返却文言の完全一致ではなく、仕様と各実装の宣言した方針に沿って判定する。
+4. 一部scope承認や別hintの具体的な利用者が現れた場合に、その機能だけを追加検討する。