rodauth-ciba 0.1.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2cf78ffc87f7347b2d1fbdd6742bd1a4bf7869f18da55011b6c8ebe691d99781
-  data.tar.gz: 5e18ae4dfe1cf251d814400f4d3bc797a394c29c86ec0bae06d7ec2ad5abc531
+  metadata.gz: 5712de096045c1433694695a5ced5e8f2fb10133448f1b7a9a4c9765ce162fbb
+  data.tar.gz: a593cf64b2dd4f0886843238ff30147f9a24a6c1f0f13ade898aeaf204eef477
 SHA512:
-  metadata.gz: a7839427730506c42a442662cfe0913f5253ce56b1bdae49658924247a08700c16f2b93f7f4d33786b2058c78204d1fa5e79b8ad624052145383959adcf81e48
-  data.tar.gz: b66028b11a05ce189271fc482181dc95b04cc6378affc00e1a1a097450fe4ee1127d3b205c42e2205bc4d450de4ef299bc44f6511071d1ef0e49da1f67cde4d5
+  metadata.gz: 2ede7d3a6d8235fc8ab8fbded2edbc49e492c036fa95573055fd8b25b27811536c3bf56443be2cdbbfbe23423c65e33f735943c67628d4c48c3da9709c1f500c
+  data.tar.gz: 1b8a08dc2b16a479e58c200bd46a3c2fb2d3957a4d3a610e2f5991e562c674d75286983afc982b96578eae9c060228275a5e497ee8b05dfccee1bc6e2bb797d5

data/CHANGELOG.md

@@ -1,6 +1,42 @@
 # Changelog
 
-## 0.1.0 — publication pending
+## 0.2.1
+
+Prepared on 2026-10-22. Incorporates the unpublished 0.2.0 candidate and corrects
+its stale documentation. The existing v0.2.0 tag is retained; no 0.2.0 gem was
+published.
+
+The official OpenID Conformance Suite has not been executed. Refresh tokens,
+pairwise subjects and dynamic CIBA registration remain experimental and disabled
+by default. This release does not claim certification or full CIBA conformance.
+Do not run old and new workers together during this upgrade.
+
+- Keep initial and refreshed token identity/key metadata bound to the successful
+  client authentication snapshot across concurrent registration updates.
+- Preserve issued UserInfo subjects after a client changes its subject_type,
+  including opaque/JWT tokens without the optional claims capability.
+
+- Bind refresh ID Tokens to the actual initial issuer/subject/audience and
+  disclosed auth_time using versioned JSON in existing storage. Preserve the
+  context through rotation and pairwise sector changes; omit refresh nonce.
+- Reject legacy or invalid refresh contexts before hooks or mutations. This
+  requires reauthentication for old refresh tokens and coordinated worker updates;
+  no automatic data migration or new database column is introduced.
+
+- Enforce requested public/pairwise subjects and essential ACR at approval,
+  issuance and refresh; preserve ordinary value/values filters on issued tokens.
+- Keep pairwise UserInfo subjects bound to their issuance and prevent mandatory
+  nonce or signed UserInfo claims from bypassing qualifier validation.
+- Accept positive integral JSON numbers in signed requested_expiry.
+
+- Measure CIBA request expiry from handler receipt before client/hint validation,
+  without extending it for synchronous processing delays.
+- Require saved authentication time for accepted max_age and essential auth_time
+  requests during approval, issuance and refresh without inventing timestamps.
+- Add a responsibility-separated Core final requirement ledger and explicit
+  conformance-suite acceptance gates; no certification or full-conformance claim.
+
+## 0.1.0 - 2026-10-11
 
 First release of the CIBA OpenID Provider extension for rodauth-oauth.
 

data/README.md

@@ -1,6 +1,6 @@
 # rodauth-ciba
 
-CIBA OpenID Provider extension for **rodauth-oauth**, with default poll and optional ping. Version 0.1.0 is prepared for its first release; RubyGems publication is pending.
+CIBA OpenID Provider extension for **rodauth-oauth**, with default poll and optional ping. This checkout documents version 0.2.1. Check [RubyGems](https://rubygems.org/gems/rodauth-ciba/versions) for published versions. See the [upgrade notes](docs/release-readiness.md#upgrade-to-021) before upgrading from 0.1.0.
 
 It adds a backchannel authentication endpoint, Discovery metadata, Ruby approval/denial APIs, transactional hooks and post-commit observation events. Your app handles customer authentication, consent UI, notification transport, business authorization and any later delegation.
 
@@ -19,12 +19,12 @@ Optional [signed authentication requests](docs/signed-requests.md) use registere
 
 ## Install
 
-Ruby>=3.3 is required. Until a registry release exists, build from this checkout:
+Ruby>=3.3 is required. To build version 0.2.1 from this checkout:
 
 ```sh
 bundle install
 gem build rodauth-ciba.gemspec
-gem install ./rodauth-ciba-0.1.0.gem
+gem install ./rodauth-ciba-0.2.1.gem
 ```
 
 The initial dependency bounds are intentionally narrow: rodauth-oauth1.7.0, Rodauth2.28.x, Sequel5.108.x and JWT3.3.x. Your application supplies its DB adapter and existing Rodauth/OAuth schema.
@@ -99,7 +99,7 @@ ruby bin/verify-package            # build, install outside checkout, run all sm
 
 The Docker runner builds the Ruby image, waits for database health, runs the same suite on each DB and removes its containers/network on exit. DB ports are not published. Data is on tmpfs; each test owns a random database. Only images/build cache remain. `pg` and `mysql2` are an optional Bundler group enabled inside Docker. The macOS/mise equivalent is `mise exec ruby -- ruby test/run.rb`.
 
-[Release readiness](docs/release-readiness.md) records the current release checks and review limits. [Release validation](docs/release-validation.md) preserves historical results. The [authentication-fix CI run](https://github.com/kajisha/rodauth-ciba/actions/runs/36710533803) passed the Ruby 3.3/3.4/4.0 SQLite jobs and the Docker database job. CI results apply to the tested commit, not to future changes.
+[Release readiness](docs/release-readiness.md) records the current release checks and review limits. [Release validation](docs/release-validation.md) preserves historical results. The [0.2.0 candidate CI run](https://github.com/kajisha/rodauth-ciba/actions/runs/39522218593) at commit `1ab56c35aead54158c3a38405da6ce3c2c443663` passed the Ruby 3.3/3.4/4.0 SQLite jobs and the Docker database job. CI results apply to the tested commit, not to later documentation or code changes. The official OpenID Conformance Suite has not been executed.
 
 ## License
 

data/docs/api.md

@@ -1,4 +1,4 @@
-# Configuration and Ruby API (0.1.0)
+# Configuration and Ruby API (0.2.1)
 
 Optional [login_hint_token](login-hint-token.md) uses `ciba_login_hint_token_enabled` and a required application resolver; no schema migration is needed.
 
@@ -217,10 +217,13 @@ Cleanup returns the deleted count. The cutoff must be an integer epoch second no
 Implement `trigger_ciba_authentication_device(snapshot)` to initiate your application’s authentication/approval flow. It runs synchronously after the request transaction/savepoint finishes and before the successful Backchannel response. The frozen snapshot contains the saved internal request ID and account/client references, not the public auth_req_id or its digest. The callback may enqueue work or call the Ruby result API. It must return normally to allow a success response; it must not perform a Rack halt/throw. Its default raises `CibaSupport::ConfigurationError`, reported as HTTP 500 `server_error`. A deliberate no-op is appropriate only if the application already processes pending requests independently (as the local demo does).
 
 Dispatch should enqueue work promptly instead of waiting for customer interaction.
-Its synchronous execution consumes the saved request lifetime; `expires_in` is not
-reduced for this elapsed time. Both the gem and reference OP can acknowledge an
-already expired request if dispatch outlasts its lifetime. See the
-[measured timing contract](research/acknowledgement-time-contract.md).
+Its synchronous execution consumes the saved request lifetime, measured from entry
+to the backchannel handler before client/hint validation. `expires_in` remains
+that lifetime, not seconds remaining at response. Slow dispatch can exhaust the
+lifetime before acknowledgement; subsequent polling then returns expired_token.
+The gem does not extend the deadline for that delay. This differs from the older
+[measured reference timing](research/acknowledgement-time-contract.md). See
+[conformance boundaries](ciba-conformance.md).
 
 
 A callback exception goes to `report_ciba_processing_error`, not the observer-error reporter. Without a surrounding application transaction, the saved request remains: notification may already have happened, so failure cannot safely undo external effects. The client does not receive an auth_req_id on that failed response. A client retry creates a new request; the app must deduplicate notifications and expire/recover abandoned requests. This is not durable delivery.

data/docs/authentication-claims.md

@@ -4,6 +4,12 @@ Approval saves the application's verified `auth_time`, `acr` and `amr`. Saving a
 value does not by itself select it for disclosure in a newly accepted request.
 Initial and refreshed ID Tokens use the same stored selection:
 
+Refresh sources additionally retain the actual initial issuer, subject, audience
+and disclosed authentication time in a versioned JSON object. Refreshed ID Tokens
+retain that original context, use a new issuance time and omit nonce. Legacy
+refresh JSON cannot prove the initial values and is rejected. See the
+[refresh migration](refresh-tokens.md#original-id-token-binding-and-migration).
+
 - `require_auth_time: true` or configured `default_max_age` client metadata selects
   `auth_time` at request acceptance. This is output selection, not freshness enforcement.
 - A nonempty `acr_values` request selects `acr`. If omitted or empty, registered
@@ -21,9 +27,13 @@ ciba_authentication_claims_by_scope "openid" => %w[auth_time acr amr]
 The default mapping is empty. Only the three names above are considered. Scope
 selection uses the scopes authorized for the current issuance, including refresh
 narrowing. It is application configuration, not a client-supplied mapping.
+For refreshed `auth_time`, the initial disclosure is authoritative: an initially
+absent claim stays absent, and a disclosed claim keeps its original value even
+if the scope mapping is subsequently changed.
 Client metadata and explicit request selection are saved at acceptance; replacing
 client metadata later does not reinterpret an accepted request or refresh source.
-An accepted `require_auth_time: true` is saved as the `auth_time_required` marker
+An accepted `require_auth_time: true`, selected `max_age` (including zero), or
+`claims.id_token.auth_time.essential: true` is saved as the `auth_time_required` marker
 in the existing authentication selection. Approval requires a verified
 `auth_time` and rejects a missing value before changing the pending request.
 Issuance and refresh reject an incomplete required context with `invalid_grant`

data/docs/ciba-conformance.md

@@ -0,0 +1,58 @@
+# CIBA Core conformance boundaries
+
+This local change targets [CIBA Core 1.0 final](https://openid.net/specs/openid-client-initiated-backchannel-authentication-core-1_0-final.html), not every optional OpenID/OAuth profile. Supported release scope is poll plus documented opt-in ping, signed requests, identity hints and user codes. Push is not implemented or advertised. Pairwise and CIBA dynamic registration remain experimental and disabled by default.
+
+[Requirement ledger](ciba-core-requirements.json) separates mandatory, prohibited, recommended, conditional and optional requirements, as well as gem/upstream/application/client/deployment responsibilities. Its 159 inherited CIBA decomposition rows plus five OIDC conditional rows are an authored inventory, not an official denominator. Historical evidence is not promoted to a current conformance pass. Grouped tests support specific boundaries, not an exhaustive proof for each row.
+
+## Design and changes
+
+The backend additionally enforces requested public/pairwise subjects and essential ACR value conditions at approval, issuance and refresh. Issued projections retain ordinary value/values filters for both targets. Generic essential claim absence is allowed; voluntary ACR has its specific semantics. Mandatory nonce and final signed UserInfo claims cannot bypass filtering, and pairwise UserInfo retains its issuance subject. Positive integral JSON numbers are accepted for signed requested_expiry. See claims and operations for legacy-token migration limits.
+
+1. Capture request receipt at entry to the backchannel POST handler, before client authentication, signed-request verification or hint resolution. Store created_at at that point and expires_at = created_at + chosen lifetime. This is the earliest protocol-handler timestamp, not a guarantee about time spent in a reverse proxy or Rack body parsing before the handler.
+2. Keep expires_in equal to the selected positive lifetime, measured from that receipt point as specified in CIBA section7.3; do not reinterpret it as seconds remaining at response.
+3. Do not add a new Backchannel error for slow processing. Section7.3 does not independently forbid acknowledgement after processing exhausts the lifetime; polling an expired source returns expired_token. The token endpoint503 provision is not a Backchannel authentication error permission. Applications must promptly enqueue AD work and clean up/reconcile abandoned requests; fixed expires_in is not guaranteed remaining lifetime on receipt of the response.
+4. Save auth_time_required when client require_auth_time=true, max_age is selected, or claims.id_token.auth_time.essential=true. Reuse the existing approval/issuance/refresh guards. Null or essential=false requests remain voluntary. No fabricated timestamps or schema migration.
+5. Continue delegating actual authentication and freshness to the application. max_age=0 requires fresh authentication; merely supplying an arbitrary timestamp is insufficient. The gem checks required context presence and requested essential ACR values; the truth of authentication and attribute evidence remains an application obligation.
+
+Refresh stores the actual initial iss/sub/aud and disclosed auth_time in versioned
+existing JSON storage, preserves the context through rotation, rejects old or
+invalid contexts before mutation, and omits refresh nonce. See the
+[migration contract](refresh-tokens.md#original-id-token-binding-and-migration).
+This fifth conditional OIDC requirement is in the backend ledger
+(164 total authored rows) even though
+refresh/pairwise remain experimental. The latest local validation does not
+establish the official suite or every optional combination.
+
+## Requirement ownership and acceptance gates
+
+| Area | Gem / upstream boundary | Application or deployment gate |
+|---|---|---|
+| Discovery and registration, section4 | Advertise only enabled modes/algorithms/flags; require configured confidential client, delivery mode and CIBA grant. Upstream owns ordinary OP metadata/authentication. | Stable HTTPS issuer/endpoints, approved client/key ownership. Experimental pairwise/DCR needs separate profile verification. |
+| Request, sections7–7.2 | TLS/form/UTF8, one hint, openid, size/type checks, registered authentication, JWT verification, signed inner inputs, unknown parameters ignored. | Correct hint-to-account/tenant mapping; login_hint_token signature/issuer/profile validation; required hint retention policy. |
+| Signed request, section7.1.1 | Asymmetric registered keys, mandatory claims, issuer/audience/date/type verification; client-auth JWT replay ledger is separate. | Client supplies unique request jti and no unsigned authentication parameters. The gem does not consume request-jti and does not claim request replay prevention. It creates new requests requiring new consent. |
+| Binding/user code, sections7.1–7.1.2 | Optional metadata and bounded inputs, required validation callbacks, errors. | Display quality, user-code enrollment/change/password distinction, code verification/rate limit. Client never stores user code. |
+| Acknowledgement, section7.3 | 256bit opaque ID, allowed alphabet, receipt-based lifetime, positive interval; processing never extends the deadline. | Proxy/queue delays before the handler, prompt dispatch and client expiry tracking. |
+| Authentication/consent, section8 | Completion account/client/scope binding, trusted context types, transactional decisions. | Real AD authentication, consent UI, CSRF/authority checks, achieved acr, freshness and business policy before approval. |
+| Token, sections10–11 | Client-bound source, current consent/openid/account/client checks, one-time issuance, locks/CAS/rollback, pending/slow_down+5/expiry/denied errors. | Same database, supported schema; RP does not overlap polls and obeys intervals. Outer transactions/overrides need integration tests. |
+| Ping, sections9/10.2 | HTTPS POST after commit, auth_req_id-only body, Bearer notification token,200/204, no redirects; SSRF/DNS/TLS/size/time boundaries. | Client notification-token entropy and callback validation; endpoint administrative ownership; durable delivery/retry and logs. |
+| ID Token, section10.1.1 / OIDC Core2 | Upstream core fields and signature plus RP audience, saved authcontext/nonce, required auth_time guard. | Valid signing setup, real authcontext, freshness and business policy. Push-only hash/id claims are not applicable. |
+| Errors, sections11/13 | HTTP/JSON envelope, safe descriptions, client-auth401, policy403, token-state errors. | Custom callback error handling and log confidentiality. Optional error_uri absent; its output-specific restriction is not applicable. |
+| Recommendations, sections14/15 | Optional hint validation and privacy-preserving persistence; protected outbound transport. | Reasonable expired-hint retention, notification ownership, privacy identifiers/retention, user matching and anti-abuse controls. |
+
+The gem cannot certify an arbitrary consuming OP: several mandatory requirements explicitly need application authentication/consent and trusted deployment configuration. Referenced RFCs and OIDC Core bring their own requirements. DPoP/mTLS/resources/RAR tests cover documented extension boundaries, not all profile combinations.
+
+## Regression evidence
+
+The initial exploratory regression run on unmodified0.1.0 had5tests/4failures/0errors. One expectation rejected an expired acknowledgement; independent specification review showed that expectation added an unsupported503 and was removed. The retained regressions cover late receipt timestamp, approval without requested required auth_time, and issuance after authentication context was removed. The delayed-dispatch test checks that polling returns expired_token without extending the receipt-based deadline. Final test results are recorded in the delivery report.
+
+The existing requirements timing test now expects the Core receipt-based policy rather than equality with node-oidc-provider9.12.2. The reference fixture still describes the reference's old measured behavior; that difference is deliberate and is not a conformance oracle.
+
+The complete suite, installed-package verification and applicable platform coverage are reported with actual command results in the delivery report. Older checked-in validation logs apply to their recorded source snapshots only.
+
+## Official conformance suite
+
+The [OpenID Foundation suite](https://gitlab.com/openid/conformance-suite) is available for local or hosted testing; [testing is free](https://openid.net/certification/about-conformance-suite/), formal certification has a separate submission process. The published [CIBA OP testing instructions](https://openid.net/certification/fapi_ciba_op_testing/) address FAPI-CIBA: that profile imposes additional requirements and is not an automatic Core-only test result.
+
+An executable OP deployment, suitable registered clients/keys, reachable TLS endpoints, and an AD flow capable of completing the suite's user scenarios are needed. Hosted testing additionally requires the suite to reach the OP; local suite setup depends on its Java/database/container runtime. No hosted account, client authorization configuration, public endpoint, credentials or certification submission is created by this change. No official suite run or certification is claimed.
+
+Next acceptance gates: run a pinned official plan against an isolated complete OP/AD deployment, document any profile-specific extras, retain machine-readable results, and audit each enabled optional combination plus all application contracts. Full Core conformance remains unproven until those gates and the ledger's open responsibilities are verified.