rodauth-ciba 0.1.0

data/docs/research/client-assertion-algorithm-contract.md

@@ -0,0 +1,177 @@
+# Configured client assertion algorithm matrix
+
+This comparison explicitly configures twelve advertised authentication algorithms:
+RS256/384/512, PS256/384/512, ES256/384/512 and HS256/384/512. The first nine use
+private_key_jwt; the HMAC algorithms use client_secret_jwt and a64-byte client
+secret. Shared-secret authentication requires upstream's plaintext-secret mode;
+this fixture is not a recommendation to weaken an existing hashed-secret store.
+
+Both actual node9.12.2 HTTP endpoints authenticate each configured algorithm and
+reject the wrong key. Token collection while pending returns authorization_pending
+only after successful client authentication. The Ruby integration additionally
+approves each request and obtains a signature/issuer/audience-verified ID Token.
+Wrong audience or issuer and wrong keys do not create/consume the request. The
+HMAC wrong key is the OP key, ensuring the client secret is the verification key.
+
+The matrix checks that Discovery's algorithm list equals the configured list;
+it does not infer algorithm support solely from a generic JWT library constant.
+The shared metadata test separately checks OAuth/OIDC equality. Basic/post and
+actual TLS authentication remain in their dedicated fixtures, not this JWT test.
+
+- [Pinned reference](../validation/node-client-auth-algorithms.txt)
+- [Gem local:1 test /137 assertions](../validation/client-auth-algorithms-current.txt)
+- [Three-DB execution](../validation/client-auth-algorithms-matrix.txt)
+
+This resolves the missing matrix for these configured algorithms. It does not
+establish all combinations of load order, management updates or sender-bound
+access tokens. CIBA signed-request Ed25519/EdDSA support does not imply Edwards
+client assertion support; the latter still follows upstream JWT capabilities.
+The upstream metadata also includes a legacy JWT assertion-type URN as an
+advertised method when plaintext secrets are enabled. This test does not claim
+that URN can independently serve as a registered CIBA authentication method;
+the registration defect is now fixed as described below. The later metadata correction below removes only the unusable URN; actual
+upstream authentication dispatch remains unchanged.
+
+## Legacy assertion-type URN is not a registered authentication method
+
+The gem previously accepted the JWT assertion-type URN as the sole registered
+CIBA authentication method. Upstream dispatch subsequently required the actual
+private_key_jwt or client_secret_jwt method, leaving this registration unusable.
+The red test records HTTP201 for that invalid configuration. The pinned reference
+instead rejects it at HTTP registration.
+
+CIBA eligibility now explicitly excludes this URN. Opt-in DCR and management
+candidate validation reuse that boundary; the normal JWT assertion_type request
+parameter remains accepted with the real registered authentication method.
+At that stage shared Discovery advertisement was left unchanged. The later
+correction below removes the URN from the advertised list without rewriting
+non-CIBA authentication dispatch.
+
+[Red regression](../validation/client-auth-urn-red.txt),
+[reference rejection](../validation/node-client-auth-urn.txt),
+[three-DB regression](../validation/client-auth-urn-matrix.txt).
+
+## Confirmed Edwards client-authentication gap
+
+The reference matrix now configures fourteen algorithms, adding Ed25519 and
+EdDSA. Both authenticate the backchannel and token endpoints; wrong keys return
+401 at each. This is separate from signed authentication request verification.
+[Reference execution](../validation/node-client-auth-edwards.txt).
+
+The initial explicit gem probe (now promoted into
+[regression tests](../../test/ciba_edwards_auth_test.rb)) signs with
+OpenSSL, registers an OKP Ed25519 client key and pins each authentication
+algorithm. Both algorithms initially returned401 invalid_client at both endpoints
+([red execution](../validation/client-auth-edwards-red.txt)). Each token test has
+its own pre-approved request, avoiding replay from masking authentication.
+That initial failing probe was not counted among the331 passing regression
+tests. The implementation increment below replaces it with passing regressions.
+
+Upstream dispatch correctly selects private_key_jwt for non-HMAC algorithms.
+The missing boundary is JWT/JWK verification: the CIBA private-key method passes
+client keys to the upstream JWT backend, while the existing Ed25519 public-key
+importer is used only for signed CIBA requests. Authentication algorithm metadata
+also derives from upstream OP signing keys; adding an Edwards verifier alone
+would leave registration/Discovery incomplete.
+
+The next implementation must provide explicit authentication-algorithm
+configuration and matching metadata, use client OKP keys (never OP fallback),
+retain audience/issuer/subject/expiry/nbf checks and assertion replay protection,
+and exercise wrong keys, registered algorithm mismatch, inline/remote keys and
+non-CIBA behavior. Edwards ID Token signing is a separate boundary and must not
+be advertised as a side effect of client authentication support.
+
+## Initial Edwards authentication implementation
+
+`ciba_client_assertion_signing_algorithms` is optional (default nil retains
+upstream-derived registration defaults). An explicit array configures the CIBA
+client assertion algorithms independently of OP token-signing keys. For example,
+`%w[RS256 Ed25519 EdDSA]` permits those algorithms for CIBA clients. OAuth and
+OIDC Discovery add these capabilities to the upstream authentication list; they
+do not remove upstream capabilities or alter ID Token algorithm advertisement.
+
+Edwards verification uses the existing local RFC8410 Ed25519 importer with the
+client's registered OKP key. It checks exact alg/curve, kid, use, key_ops, signature
+length and signature over the original compact bytes. No global ruby-jwt
+algorithm or OP signing key is installed. Unknown critical headers and duplicate
+JSON fields are rejected. Shared issuer/subject/expiry/iat/audience checks and
+atomic assertion replay storage remain in the existing authentication wrapper;
+the Edwards decoder additionally validates nbf.
+
+DCR accepts the algorithms only when explicitly enabled for private_key_jwt and
+rejects them for client_secret_jwt. The two new tests check Discovery, registration,
+both endpoints, wrong signing keys, key metadata, malformed/future nbf, expiry,
+issuer/audience and replay. The existing twelve-algorithm test remains in the
+regression subset. [Three-DB execution](../validation/client-auth-edwards-matrix.txt).
+
+The follow-up below adds remote keys, ordinary-flow coexistence and installed
+artifact evidence. Full authentication-workstream completion is not inferred.
+
+## Remote keys and installed authentication follow-up
+
+A real HTTP JWKS fixture now exercises both Edwards algorithm names. A live cache
+retains its old key, explicit cache invalidation switches to the replacement key,
+and the old signature then fails. This is deterministic cache expiry, not a
+wall-clock TTL measurement.503 and invalid JSON reject authentication without
+creating requests or consuming the saved approval; recovery permits token
+collection with a signature-verified ID Token. Each CIBA-capable client also
+authenticates a normal authorization_code token exchange using its Edwards key.
+
+[Three-DB execution](../validation/client-auth-edwards-remote-matrix.txt): five
+related tests /247 assertions per DB, no failures/errors/skips. The reference
+fixture independently fetches real HTTP remote JWKS for both Edwards names and
+rejects wrong keys at both CIBA endpoints
+([execution](../validation/node-client-auth-edwards-remote.txt)). Its new remote
+cases do not claim identical rotation/failure-cache policy.
+
+The installed artifact smoke adds Edwards authentication at both endpoints,
+assertion replay rejection, customer approval, opaque/JWT access tokens and
+verification of the OP's RS256 ID Token. The sample explicitly creates the
+client assertion replay table before enabling authentication.
+[Installed execution](../validation/client-auth-edwards-installed.txt).
+This authentication smoke uses inline keys; HTTPS Edwards client-key retrieval
+in the installed package is not established by it.
+
+The full suite on Ruby3.3 and3.4 now passes334 tests /4,316 assertions per
+version, with the existing two SQLite row-lock skips
+([execution](../validation/client-auth-edwards-rubies.txt)). The installed artifact
+includes this contract document and passes the package-presence check; SHA256
+`d43fd74be78fc8f615a8f6125488af244dda284820ae723293696d20c6d61edf`.
+That artifact predates this results paragraph; implementation is unchanged.
+
+## Installed HTTPS retrieval and configuration scope
+
+The installed TLS fixture now serves Edwards client JWKS over HTTPS for both
+algorithm names and both opaque/JWT configurations. Default loopback filtering
+rejects retrieval before the handler; the fixture then allows exactly its owned
+loopback address while preserving certificate verification. Trusted TLS permits
+authentication at both endpoints and issuance of a verified ID Token. A separate
+process without trust in the fixture CA rejects authentication without any key
+handler access or persisted CIBA request. JWKS requests are GETs without forwarded
+authentication credentials.
+[Execution](../validation/client-auth-edwards-https-installed.txt), SHA256
+`d99ffb61d2645e040b3a7ab1bbc0240e38c743d778a978d37aa9717020ac1a4c`.
+This artifact predates this report paragraph.
+
+The configuration-scope regression sets the CIBA list to Edwards only, then
+authenticates an unrelated RSA authorization_code client. It succeeds without
+CIBA request or replay-ledger writes; shared Discovery retains RS256 alongside
+the explicitly added Edwards capabilities.
+[Three DBs](../validation/client-auth-edwards-scope-matrix.txt): five tests /114
+assertions each, no failures/errors/skips. This closes the configured-method
+coverage gap. The remaining legacy-URN metadata mismatch is corrected below.
+
+## Shared authentication-method metadata correction
+
+OAuth/OIDC Discovery now removes the assertion-type URN from
+`token_endpoint_auth_methods_supported`, matching the reference. Both discovery
+documents retain the same remaining list. The underlying upstream method list
+and dispatch are untouched: no authentication mode is globally disabled, and
+ordinary RSA clients still authenticate. The normal client_assertion_type
+parameter remains required for JWT assertions.
+
+[Initial mismatch](../validation/client-auth-metadata-urn-red.txt),
+[reference Discovery and registration](../validation/node-client-auth-metadata-urn.txt),
+[three DBs](../validation/client-auth-metadata-urn-matrix.txt): four tests /162
+assertions each, including existing twelve-algorithm authentication and normal
+OAuth coexistence. This resolves CIBA-007 for the configured metadata boundary.

data/docs/research/completion-error-boundaries.md

@@ -0,0 +1,56 @@
+# Poll completion errors: protocol boundary versus generic result API
+
+## Current alignment finding
+
+The gem now persists a generic completion error and returns it once before
+rejecting replay with `invalid_grant`. Codes are validated as bounded OAuth
+error strings; descriptions are not an input to the Ruby API. Existing denials
+retain NULL and continue returning `access_denied`. The negative state and
+transactional denial hooks are retained, while observation distinguishes a
+technical `failed` event from customer `denied`. Migration, idempotent retry,
+conflicting completion, hook rollback and ping have direct tests.
+
+The latest reference HTTP test also covers a custom `application_failure` and
+an application-provided description. Both `transaction_failed` and the custom
+code are returned once with HTTP 400, followed by `invalid_grant`. Neither
+retains the supplied description. In 9.12.2, `backchannelResult` assigns
+`error_description`, while the model persists `errorDescription`; the grant
+handler reconstructs the error from the latter. The measured response bodies
+contain only `error` for these two cases. Do not infer a public description
+round-trip from the input object's API. [Execution](../validation/node-completion-error-descriptions.txt)
+and [fixture](../../test/reference/full-op/lifecycle.mjs).
+
+2026-09-30. Reviewed CIBA Core and executed the complete node-oidc-provider v9.12.2 on Node24.21.0 with its built-in memory adapter.
+
+[CIBA Core §11](https://openid.net/specs/openid-client-initiated-backchannel-authentication-core-1_0.html#token_error_response) defines polling errors and distinguishes pending, throttling, expiry and denial. `transaction_failed` appears in the [Push error payload, §12](https://openid.net/specs/openid-client-initiated-backchannel-authentication-core-1_0.html#push_error_payload), not the poll-specific additions. Pending and slow_down describe continuing requests; expiry follows the request deadline. This does not define an application-to-OP completion API.
+
+## Observed behavior
+
+The complete reference OP accepted both `TransactionFailed` and `AuthorizationPending` through `backchannelResult`. Polling returned the supplied error once, consumed the request, and returned `invalid_grant` on the next poll. This verifies the generic error propagation in `provider.js` and `grant_common.js`; it does not establish those application-supplied results as suitable terminal poll outcomes.
+
+The earlier access_denied-only restriction has been removed. The public API
+still does not duplicate node's error class hierarchy: it accepts a
+`CibaSupport::ProtocolError` code. Passing a continuing-state error as a result
+is a terminal application decision, not a substitute for normal pending polls.
+This matches the reference's one-use completion semantics without treating an
+application outage as customer refusal. The default completion HTTP status is
+400; invalid_token and insufficient_scope use401/403 as in the reference.
+
+## Device-dispatch exception comparison
+
+The reference harness records a request in the application's dispatch callback and then injects an exception. HTTP initiation returns 500 without auth_req_id, but the pending request remains in the adapter and can still be polled using the internally observed identifier. This matches the gem's existing `test_device_failure_is_not_an_observer_failure_or_success_response`. No test here demonstrates actual notification delivery or durable recovery.
+
+## Evidence
+
+- [Node LTS HTTP log](../validation/node-full-op-lts.txt): generic completion errors, dispatch failure and prior lifecycle scenarios.
+- [Gem log](../validation/completion-boundaries.txt): Ruby4.0.6 / SQLite, 105 tests / 783 assertions, no failures/errors/skips.
+- [Gem regression test](../../test/ciba_alignment_test.rb): rejects transaction_failed, authorization_pending, slow_down, expired_token, invalid_grant and server_error as completion results without mutation.
+- The prior Ruby/DB matrix covered 104 tests. No runtime or schema change was made for this review; the added test has not been rerun on every matrix entry.
+
+## Current gem evidence
+
+[Focused regression](../validation/completion-errors-current.txt) passes7 tests /166 assertions.
+The old105-test log and unsupported-error regression above describe the previous
+implementation, not the current API.
+
+Ruby3.4 SQLite/PostgreSQL/MySQL each pass18 tests /339 assertions ([matrix](../validation/completion-errors-matrix.txt)). The [installed artifact](../validation/completion-errors-installed.txt) verifies custom failure/replay alongside existing smokes; SHA256 `0b0b395c7ff90ffe4e697afe7f5c17c18bc7d8d339e4134415d65ca384a76626`.

data/docs/research/consent-api-evolution.md

@@ -0,0 +1,59 @@
+# Request and consent API evolution review
+
+2026-09-30. Reviewed the installed node-oidc-provider 9.12.2 source, rodauth-oauth 1.7.0 source and the current gem. This is an implementation review and staged design proposal, not an announcement that the additional capabilities are available.
+
+## Finding
+
+Keep the public boundary `backchannel_result(request_id, saved_grant_or_id, ...)`. Reloading consent by ID, checking account/client ownership, and serializing issuance with revocation are appropriate foundations for richer consent. Do not replace that boundary with caller-supplied token claims or authorization hashes. Current snapshots are scope-only; their existence is not evidence of node's complete Grant model.
+
+The next extension needs separate requested and approved representations. Simply copying `claims` or `resource` into upstream OAuth grant columns could bypass consent. In upstream `generate_id_token`, keys from stored ID Token claims are added to the requested scope/claim list before the account provider runs; this is not a substitute for the gem's approval filtering. Resource handling also needs per-resource authorization rather than one global scope intersection.
+
+## Concrete migration and API shape
+
+Update: nonce propagation is now implemented with a nullable request column and explicit forward-migration helper. Its scope/identity separation remains as described below; other additions in this table remain proposals. See [API](../api.md) and [operations](../operations.md).
+
+Further update: [optional explicit claims](../claims.md) now implements request/consent separation and both output targets. The API uses `claims:` and `rejected_claims:` arrays on `create_ciba_grant`; predicates remain available in request JSON for application policy. [Resources](../resources.md) also implement their separate saved permission and token audience. RAR and additional result errors remain proposals; the [RAR reference contract](rar-reference-contract.md) now supplies actual CIBA HTTP evidence and completion-policy boundaries.
+
+These are proposed additions for individually selected increments. They must not be accepted or advertised until implemented and tested.
+
+| Capability | Request storage | Consent storage / proposed API | Issuance and rejection boundary |
+|---|---|---|---|
+| Explicit OIDC claims | Validated `requested_claims` JSON, split by ID Token/UserInfo target | Optional `oidc_claims:` and explicit rejected claims on `create_ciba_grant` | Intersect requested claims with consent and current client policy before invoking upstream claim acquisition. Preserve essential/value constraints for validation; do not flatten them into unrestricted claim names. Keep protocol-required claims separate from optional disclosure. |
+| Resources | Validated requested resource identifiers, preserving multiple values | `resources: {resource_uri => scopes}` on saved consent | Selected resource must be both requested and approved. Limit access-token scope/audience per resource; ID Token audience remains the client. Invalid or unauthorized target must not fall back to unrestricted issuance. |
+| Nonce | Validated request nonce | No consent field: it is request correlation, not a permission | Persist through completion and include the original value in the ID Token. A poll parameter must not replace it. |
+| RAR | Validated requested authorization details | Separately approved authorization details, with type-specific validation | No generic JSON merge or equality-as-authorization. Specify a type's narrowing rules and downstream enforcement before implementing it. No reviewed upstream RAR bridge currently establishes this behavior. |
+| Additional completion errors | Persist explicit terminal error code independently of successful grant ID | Continue accepting a typed result error; extend only a documented allowlist | Define which errors are terminal, their polling responses and retry equivalence. Current `denied` state plus grant absence encodes only access_denied; adding Ruby subclasses alone is insufficient. Never expose exception messages as protocol descriptions. |
+
+The resource increment now accepts `create_ciba_grant(account_id: ..., oauth_application_id: ..., scopes: "openid", resources: {"https://api.example.test" => "read"})` after its explicit migration and activation. Existing scope-only calls and `backchannel_result(id, grant)` retain their meaning; granting `openid` does not implicitly authorize a newly added resource.
+
+Use explicit forward migrations for each selected increment, initially with nullable new columns. Existing rows mean no additional explicit authorization; do not backfill consent from request parameters. Claims implicitly permitted by existing scope semantics need a documented compatibility mapping before enabling explicit claims rejection. Check existing client/application eligibility during issuance as today.
+
+A mixed-version deployment needs a capability gate: migrate first, deploy readers/writers, then enable the feature only once all workers understand it. Old workers must not process richer grants as scope-only grants. If rolling compatibility cannot enforce this, drain old workers before activation. Downgrade cannot silently discard richer approval restrictions; require deactivation and handling of affected pending requests. Keep the existing consent-to-issued-token link and revocation behavior through every migration.
+
+## Consent lifetime difference
+
+node's default `GrantTTL` is 14 days. The follow-up implementation now applies the same default to new gem consent via `ciba_grant_lifetime`. Omitted expiry uses that configured lifetime; explicit nil or a future timestamp remains an application override. This changes the earlier default of nil for newly created rows, including convenience approval.
+
+Existing rows retain their original expiry without migration. Access-token lifetime and request lifetime remain separate. The tests cover default/explicit/custom expiry, preservation of legacy nil rows, expiry at collection and during approval/issuance hooks; the complete node OP test now reloads saved Grant data and checks its actual exp-minus-iat value.
+
+## Acceptance gates
+
+The [resource reference contract](resource-reference-contract.md) supplies real HTTP tests and identifies the need for separate OIDC/access-token scope handling; merely enabling upstream resource_indicators is insufficient for CIBA consent binding.
+
+The [explicit-claims reference contract](claims-reference-contract.md) now provides passing complete-OP cases for requested/allowed/rejected values and ID Token/UserInfo target separation. It also identifies the upstream UserInfo filtering path that the gem implementation must cover.
+
+- Retain tests proving that mutating a supplied grant snapshot cannot broaden consent, that account/client mismatches fail, and that revocation serializes with issuance.
+- Each new field needs positive tests and negative tests for unrequested/unapproved values, request/poll tampering and partial consent. Exercise the upstream claim provider with assertions that rejected data is never requested or emitted.
+- JSON-bearing snapshots require deep immutability or an equivalent defensive-copy contract; the current snapshot implementation only needs to freeze flat values.
+- Add forward migration tests on all three DBs and an explicit mixed-version activation test. Keep current scope-only fixtures to establish compatibility.
+- Add the selected capability to the real node HTTP harness and compare behavior, including deliberately unsupported cases. Do not infer RAR or claim enforcement from successful scope-only issuance.
+
+The current API can remain for the initial subset. This review closes the question of whether an immediate wholesale API rewrite is necessary; it does not close the feature gaps. Next implementation work should select one concrete capability and its protocol requirements, rather than introducing all of these schema fields in advance.
+
+Follow-up: the [completion-error analysis](completion-error-boundaries.md) found that node's generic error acceptance must not be equated with terminal poll errors. It preserves the current allowlist and documents an explicit cancellation/failure API as a separate future task.
+
+## Source map
+
+- node v9.12.2: `lib/models/grant.js` (openid/resources/rejected/rar), `lib/models/backchannel_authentication_request.js`, `lib/helpers/grant_common.js`, `lib/provider.js` (`backchannelResult`), `lib/helpers/defaults.js` (`GrantTTL`). Reproducible source is installed by the [locked reference package](../../test/reference/full-op/package-lock.json).
+- rodauth-oauth 1.7.0: `lib/rodauth/features/oidc.rb` (`generate_id_token`, `id_token_claims`), `oauth_resource_indicators.rb`.
+- Gem: [feature](../../lib/rodauth/features/ciba.rb), [schema](../../lib/rodauth/ciba/schema.rb), [consent tests](../../test/ciba_grant_test.rb).