@blamejs/core 0.8.59 → 0.8.64

package/CHANGELOG.md

@@ -8,6 +8,11 @@ upgrading across more than a few patches at a time.
 
 ## v0.8.x
 
+- v0.8.64 (2026-05-10) — CI green-up for v0.8.63 (wiki source-comment validator). The v0.8.62 push missed `examples/wiki/test/validate-source-comment-blocks.js` — a wiki-side validator that enforces every `@primitive` block has `@signature` starting with `b.`, matching function arity, an `@opts` declaration when the function takes opts, an `@example` block, and resolvable `@related` cross-refs. 50 findings across the new federation/VC primitives. Fixed: every nested-namespace `@signature` (`b.auth.ciba.client.X`, `b.auth.oid4vci.issuer.X`, `b.auth.oid4vp.verifier.X`, `b.auth.saml.sp.X`) re-qualified with the full `b.*` prefix instead of the bare `client.X` shorthand; arity collapsed to `(opts)` where the function takes a single opts arg; `@example` block added to every primitive; `@opts` block added to ciba.client.startAuthentication / parseNotification + openidFederation.resolveLeaf; `@primitive` block added to xmlC14n.parse; `@related` cross-refs scrubbed of dangling references to undocumented primitives (oauth.create / sdJwtVc.issuer aren't @primitive-documented yet); the parse-as-JS check on oid4vci's @example caught a `{...}` literal with no target — replaced with a concrete object spread. No primitive surface change versus v0.8.63.
+- v0.8.63 (2026-05-10) — CI green-up for v0.8.62. The v0.8.62 npm-publish workflow's lint gate flagged ten ESLint findings the local pre-ship audit missed (eslint not run before commit): unused vars (`openTag` in xml-c14n; `cache` + unused `C` import + `DEFAULT_CHAIN_TTL_MS` in openid-federation; `safeJson` in oid4vp; `sdJwtVcCore` + `SUPPORTED_PROOF_TYPES` in oid4vci), an unnecessary `\-` escape in xml-c14n's name-character regex, and a control-character regex in ciba's binding_message validator (eslint's `no-control-regex` refuses control-char ranges in regex literals regardless of `\u` escaping). Fixed by removing the dead vars + dead escape, and replacing the regex with an explicit codepoint scan in `_validateBindingMessage` that walks `msg.charCodeAt(i)` and refuses C0 / DEL+C1 / zero-width / bidi-mark / bidi-isolate / BOM ranges. No primitive surface change versus v0.8.62.
+- v0.8.62 (2026-05-10) — federation / VC primitive family + standalone DB-file lifecycle + anonymous-session ergonomics. **OpenID Connect Front-Channel + Back-Channel Logout 1.0** on `b.auth.oauth`: `parseFrontchannelLogoutRequest(req)` validates iss + sid query params; `verifyBackchannelLogoutToken(jwt, vopts)` verifies the JWS (typ=logout+jwt), validates the events claim per OIDC §2.6, refuses logout-tokens carrying nonce, requires sub OR sid, and runs an operator-supplied `seen({jti,iss,iat})` callback for jti-replay defense. Discovery surface extended to `check_session_iframe` + `backchannel_authentication_endpoint`. **CIBA Core 1.0** at `b.auth.ciba.client.create({ deliveryMode: "poll"|"ping"|"push", ... })` with `startAuthentication` / `pollToken` / `parseNotification`; supports JWT-bearer / mTLS / shared-secret client auth, binding_message + acr_values + requested_expiry, ping/push notification token (timing-safe compared via sha3 hash), and the urn:openid:params:grant-type:ciba grant. **OpenID4VCI 1.0** at `b.auth.oid4vci.issuer.create({ sdJwtIssuer, supportedCredentials, ... })` — issuer-initiated credential_offer with pre-authorized_code + tx_code, /token grant exchange, /credential endpoint with proof-JWT verification (typ=openid4vci-proof+jwt, iat freshness, nonce-replay defense, holder-key binding via header.jwk + JWS verify), c_nonce rotation per request, /.well-known/openid-credential-issuer metadata. Composes `b.auth.sdJwtVc.issuer` for SD-JWT VC minting. **OpenID4VP 1.0 + DCQL** at `b.auth.oid4vp.verifier.create({ ... })` — `createRequest` builds a vp_token authz request with a DCQL query; `verifyResponse` parses the wallet's vp_token, runs each presentation through `b.auth.sdJwtVc.verify` (audience + nonce + KB-JWT bound, optional key_attestation verifier), then runs the DCQL matcher. DCQL implementation covers credentials[] (id / format / meta vct_values / meta issuer_values / claims with path + values) and credential_sets[] (options + required) per OID4VP §6. **OpenID Federation 1.0** at `b.auth.openidFederation.{parseEntityStatement, verifyEntityStatement, buildTrustChain, applyMetadataPolicy, resolveLeaf}` — fetches entity configs from `<entity>/.well-known/openid-federation`, walks `authority_hints` up to a trust anchor (operator-pinned JWKS), verifies each subordinate-statement JWS, and applies the federation's metadata_policy (value / default / add / one_of / subset_of / superset_of / essential — unknown operators refuse). **SAML 2.0 SP** at `b.auth.saml.sp.create({ entityId, idpEntityId, idpCertPem, ... })` — AuthnRequest builder for HTTP-Redirect/POST bindings, Response parser that verifies XMLDSig (Response-level OR Assertion-level signature), defends against signature-wrapping via `b.xmlC14n.canonicalizeElementById`'s single-match invariant, validates SubjectConfirmation Bearer (NotOnOrAfter / NotBefore / Recipient / InResponseTo) + Conditions audience + Status. Plus `b.auth.saml.fetchMdq({ baseUrl, entityId, trustCertPem? })` for MDQ-style metadata fetch with optional XMLDSig verification. **`b.xmlC14n`** — RFC 3741 Exclusive XML Canonicalization 1.0 (SAML/XMLDSig subset): `canonicalize(input, opts?)` and `canonicalizeElementById(xml, id, opts?)`. The `canonicalizeElementById` single-match invariant is the core defense against XML signature-wrapping attacks (refuses ID collisions + zero-match references). Doctype + ENTITY refused at parse time. **SD-JWT VC `key_attestation` extension** — `b.auth.sdJwtVc.holder.store({..., keyAttestation })` persists a holder-side attestation JWT alongside the credential; `b.auth.sdJwtVc.present({..., keyAttestation })` embeds it in the KB-JWT header; `b.auth.sdJwtVc.verify(presentation, { keyAttestationVerifier, requireKeyAttestation })` surfaces the attestation token to an operator-supplied verifier so trust-anchor decisions (TEE / FIDO MDS3 / App Attest / Play Integrity) stay operator-side. **`b.db.fileLifecycle({ dataDir, vault, ... })`** — standalone encrypted-DB-file lifecycle for consumers that own their own SQLite handle (own schema, own migrations, own connection). Decrypts `<dataDir>/db.enc` to a tmpfs path (`/dev/shm` on Linux), exposes `dbPath` for the operator to open, runs a periodic re-encrypt flush via `startFlushTimer(db)`, returns an in-memory snapshot via `snapshot(db)`, and runs a graceful flush + cleanup via `flushAndCleanup(db, opts)`. Same envelope shape as `b.db`; no schema / audit-chain coupling. **`b.session.create({ anonymous: true })`** auto-mints `userId = "anon:" + crypto.randomUUID()` so operators running pre-login flows keep the full sealed-cookie + sealed-userId + sidHash + idle/absolute-timeout posture without rolling their own opaque-id pattern. `b.session.isAnonymous(userId)` helper for post-auth gates. `destroyAllForUser` refuses anon-prefix ids (per-session, not portable). **`validateOpts.makeNamespacedEmitters(prefix, { audit, observability })`** — collapses the recurring per-primitive `_emitAudit / _emitMetric` boilerplate into one call; new federation/VC primitives consume it. Wiki e2e regex updated for the v0.8.61 sealed-cookie format (`vault:<base64>` instead of pre-v0.8.61 hex).
+- v0.8.61 (2026-05-10) — `b.db.collection` schemaless-document opts, `b.session` PQC-sealed cookie default, `/24`+`/64` IP-prefix fingerprint binding, pluggable session store. **Operator-visible breaking change**: `b.session.create(...).token` now returns a vault-sealed envelope (`vault:` prefix, ML-KEM-1024 + P-384 hybrid + XChaCha20-Poly1305) instead of the plaintext sid. Pre-v0.8.61 raw-sid cookies fail to unseal at `b.session.verify` and the affected user re-authenticates. Pre-v1.0 ships no compat shim — every existing session force-logs-out on upgrade. Storage path unchanged: the DB still keys on `sha3('bj-session:' || sid)`, sealing only changes the wire format. **db.collection schemaless extensions**: pass `{ overflow: "data" }` to fold every insert/update field outside the table's column list into a JSON-text column; `find` / `findOne` parse it and merge keys back onto the row. `WHERE` on an unknown field rewrites to `JSON_EXTRACT(<overflow>, '$.field')` for `$eq` / `$ne` / `$in` (range / `$like` require a real column with an index). Pass `{ jsonColumns: ["roles", "metadata"] }` to auto-`JSON.stringify` listed columns on write and parse them via `b.safeJson` on read; unknown columns refuse at first use. Pass `{ sealedFields: { email: "emailHash" } }` to co-locate the sealed-column / derived-hash declaration with the collection — registers via `b.cryptoField.registerTable` so the existing query-builder sealed-field rewrite (`where({ email: "x" })` → `where({ emailHash: <hash> })`) picks up automatically. **Session fingerprint subnet binding**: `fingerprintFields: ["clientIpPrefix"]` hashes the client IP at `/24` for IPv4 and `/64` for IPv6 (per RFC 4291 §2.5.4 customer-LAN allocation), so roaming carriers' per-request IP flips no longer log out healthy mobile users. IPv4-mapped IPv6 (`::ffff:1.2.3.4`) buckets as v4 `/24`. **Pluggable session store**: `b.session.useStore(store)` swaps the `_blamejs_sessions` storage backend; first-party adapter `b.session.stores.localDbThin({ file })` wraps `b.localDb.thin` (typically pointed at tmpfs) so heavy session churn doesn't fight the main DB's WAL fsync + at-rest re-encryption cycle. `audit.FRAMEWORK_NAMESPACES` extended with `localdb` so `b.localDb.thin` open / close events stop dropping. New per-primitive Layer 0 tests: `db-collection-extensions.test.js` (29 checks), `session-extensions.test.js` (24 checks).
+- v0.8.60 (2026-05-09) — CI green-up for v0.8.59. macOS smoke runner failed `watcher.test.js: surface onChange for non-ignored file` again under SMOKE_PARALLEL=64 + GitHub-Actions-runner contention; the v0.8.56 bump from 300ms→1500ms wasn't enough on a contended Darwin runner. Replaced the fixed-budget wait with two structural fixes: (a) a 200ms priming wait BEFORE the test writes any files, so the FSEvents watcher is fully established before file-system activity races its startup; (b) a poll-until-event loop after writes that flushes + checks the change set every 100ms up to a 5s deadline, exiting early when the target event lands. Linux/Windows still finish in <100ms; the wider budget only matters on contended macOS. No primitive surface change versus v0.8.59.
 - v0.8.59 (2026-05-09) — comment cleanup. Two stale references to an external consumer name inside `lib/db-collection.js` and `lib/template.js` comments stripped — names of downstream consumers don't belong in framework source. No primitive surface change versus v0.8.58.
 - v0.8.58 (2026-05-09) — `b.db` query-builder + facade extensions, db.init opt-outs, snapshot helper, mtls path fix. **Query atoms** on `b.db.from(table)`: `.increment(column, delta)` (atomic `UPDATE col = COALESCE(col, 0) + ?`, refuses unconditional, returns rows-changed), `.whereGroup(qb => ...)` (closure-form OR composition via new `WhereBuilder` class with `.eq` / `.neq` / `.gt` / `.gte` / `.lt` / `.lte` / `.in` / `.like` AND vs `.orEq` / `.orNeq` / ... OR + `.raw`), `.orWhere(...)` (top-level OR; accepts object map / `(field, value)` / `(field, op, value)` / closure), `.search(fields, term, opts?)` (chainable LIKE-OR with `match: "substring"|"prefix"|"exact"`, `~` ESCAPE char to safely handle user-supplied `%`/`_`), `.paginate(opts)` (returns `{ items, total, limit, offset, page, totalPages }`; default limit 25, cap 1000). **Mongo facade** at `b.db.collection(name)` returning `{ insert, insertMany, find, findOne, update, updateMany, remove, count, paginate }` — maps Mongo-shape calls onto `b.db.from(name)`. Update operators: `$set` / `$inc` (composes `Query.increment`) / `$unset`. Query operators: `$eq` / `$ne` / `$gt` / `$gte` / `$lt` / `$lte` / `$in` / `$like`. Unknown operators throw at config-time. **db.init opt-outs**: `frameworkTables: false` skips provisioning `audit_log` / `consent_log` (operators with their own audit chain reuse the framework's `b.db` / `b.vault` / `b.cryptoField` primitives without the bundled chain tables — append-only triggers, chain verifies, WORM assertions, audit-signing bootstrap, checkpoint verifies, and the `audit_log` / `consent_log` reserved-name refusal all become no-ops). `auditSigning: false` (finer-grained — keep framework tables but skip the audit-signing-key bootstrap when the host manages its own signing key). **db.init path overrides**: `encryptedDbPath` (fully-qualified path to `db.enc`), `encryptedDbName` (basename under `dataDir`, default `"db.enc"`), `dbKeyPath` (encryption-key file outside `dataDir`, e.g. KMS-fronted volume). **`b.db.snapshot()`** — in-memory encrypted Buffer (same envelope `flushToDisk` writes, just held in memory; WAL checkpoint forced first so committed state captures cleanly). Plain mode returns the raw plaintext SQLite file. **`b.mtlsCa.create({ paths })` absolute-path fix** — `_resolvePaths` no longer joins absolute path entries under `dataDir`. The pre-v0.8.58 shape silently rewrote `MTLS_CA_KEY=/etc/ssl/ca.key` → `<dataDir>/etc/ssl/ca.key`, breaking operators with externally-mounted CA files. Standard `path.join` semantics already preserve absolute arguments — the always-join was an oversight. Relative entries still join under `dataDir` (back-compat). **CLAUDE.md release workflow §5** rewritten — host smoke + host wiki e2e run BEFORE container smoke + container wiki e2e, sequentially, never in parallel. Both runners write to `.test-output/smoke.log` and `.test-output/wiki-e2e.log`; parallel runs clobber each other so the log of the actually-blocking failure may be overwritten by whichever leg finishes second. The container leg writes to `smoke-container.log` / `wiki-e2e-container.log` so diagnose-after-failure is one file lookup. New per-primitive Layer 0 tests: `db-query-extensions.test.js` (27 checks), `db-collection.test.js` (23 checks), `db-init-extensions.test.js` (13 checks), `mtls-ca-paths.test.js` (7 checks). **Deferred**: configurable framework-schema column names — the original proposal was incomplete; re-open with the full spec. Configurable framework-table names (rename `audit_log` / `consent_log`) — `frameworkTables: false` covers the audit-conflict use case; the full rename touches dozens of hardcoded SQL literals across the audit + consent modules and is its own patch with a refactor proper.
 - v0.8.57 (2026-05-09) — CI green-up for v0.8.56. The v0.8.56 npm-publish workflow's smoke gate passed but the `prepack-guard` script (`scripts/check-pack-against-gitignore.js`) rejected the tarball: it ran `git check-ignore -v` against every packed path and treated EVERY matching gitignore line as "ignored", including `!`-prefixed negation rules. The newly-tracked `lib/vendor/bimi-trust-anchors.pem` matches the `!lib/vendor/*.pem` negation rule that v0.8.54 added, but the script flagged it as "gitignored in tarball" and exited 1. Fix: filter out lines whose matching pattern starts with `!` — those are negation rules indicating the file is NOT actually ignored. No primitive surface change versus v0.8.56.

package/README.md

@@ -41,8 +41,8 @@ var b = require("@blamejs/core");
 
 The framework bundles the surface a typical Node app reaches for. Every primitive listed is callable today; nothing is a stub.
 
-- **Data layer** — SQLite with sealed-by-default columns (`b.db`), migrations, seeders, atomic-file writes; bring-your-own external Postgres / MySQL / etc. with pool tuning + role-aware connect + read-replica routing (`b.externalDb`); declarative role-narrowed views and Postgres row-level-security migrations (`b.db.declareView`, `b.db.declareRowPolicy`); S3 / R2 / B2 / GCS / Azure object store with multipart upload + SSE + bucket-ops (create / delete / list / lifecycle / CORS) across all three clouds, plus S3 Object Lock + per-object retention + legal hold for write-once-read-many compliance workloads (`b.storage`, `b.objectStore`); durable queue with priority + cron + flows on the local SQLite backend, a shared Redis backend, OR AWS SQS via SigV4 + AWSJsonProtocol_1.0 for fully-managed multi-replica deploys (`b.queue`, `b.jobs`); cluster-shared cache (`b.cache`).
-- **Identity & access** — passwords (Argon2id) + policy primitive (NIST 800-63B / PCI-DSS 4.0 / HIPAA-AAL2 profiles, HaveIBeenPwned k-anonymity breach check, length / context / dictionary / complexity rules, rotation + history) (`b.auth.password`); passkeys (WebAuthn), TOTP, JWT (PQ-default), OAuth, sessions with optional IP / UA fingerprint drift detection + anomaly scoring, brute-force lockout (`b.auth.*`, `b.session`); RBAC + optional per-role DB binding + role-spec `requireMfa` + per-route MFA freshness window + ABAC predicate registry (`b.permissions`); API keys with rotation (`b.apiKey`); break-glass column gates with second-factor + audit (`b.breakGlass`); two-person-rule approval workflow with m-of-n quorum + cooling-off lock + approver-role gate + cancellation (`b.dualControl`); FAPI 2.0 Final composite posture (PAR + PKCE-S256 + DPoP-or-mTLS sender-constrained tokens + RFC 9207 issuer-in-callback) for financial / Open Banking deployments (`b.fapi2`); CFPB §1033 / FDX 6.0 consumer-financial-data-sharing wrapper (`b.fdx`); cross-table data-subject coordination (export / rectify / erase / restrict / objection) walking every table tagged with the subject's column without app-side plumbing (`b.subject`, `b.subject.eraseHard`); subject-level legal-hold registry consulted by erase + retention paths (FRCP Rule 26/37(e), GDPR Art 17(3)(e), SEC Rule 17a-4, HIPAA §164.530(j)(2)) (`b.legalHold`); adaptive bot-challenge staircase composing `b.middleware.botGuard` + `b.auth.lockout` + operator challenge / escalation hooks for auth paths (`b.authBotChallenge`); session-to-device-posture binding (UA + Accept-Language + Accept-Encoding + IP /24 prefix + optional WebAuthn-bound key) with fail-closed verify on store error (`b.sessionDeviceBinding`).
+- **Data layer** — SQLite with sealed-by-default columns (`b.db`), migrations, seeders, atomic-file writes; chainable query builder with atomic `.increment(col, delta)`, closure-form `.whereGroup` / top-level `.orWhere` OR composition, `.search(fields, term)` LIKE-OR with safe `%`/`_` ESCAPE handling, `.paginate(opts)` returning `{ items, total, page, totalPages }`; Mongo-style document-store facade `b.db.collection(name, opts?)` (`$set` / `$inc` / `$unset` / `$eq` / `$ne` / `$gt` / `$gte` / `$lt` / `$lte` / `$in` / `$like`) with schemaless-document opts — `overflow: "<col>"` folds unknown insert/update fields into a JSON-text column (and rewrites `WHERE` on virtual fields to `JSON_EXTRACT`), `jsonColumns: [...]` auto-stringifies on write + parses via `b.safeJson` on read, `sealedFields: { email: "emailHash" }` co-locates a `b.cryptoField` sealed-column / derived-hash declaration with the collection so plaintext lookups auto-rewrite to hash-column lookups; in-memory encrypted snapshot via `b.db.snapshot()`; standalone encrypted-DB-file lifecycle for consumers that own their own SQLite handle (`b.db.fileLifecycle({ dataDir, vault })` — decrypt-to-tmpfs, periodic re-encrypt flush, snapshot, graceful shutdown — same envelope as `b.db`, no schema/audit-chain coupling); `db.init` opt-outs for hosts that own their audit chain (`frameworkTables: false` / `auditSigning: false`) and configurable encrypted-file paths (`encryptedDbPath` / `encryptedDbName` / `dbKeyPath`); bring-your-own external Postgres / MySQL / etc. with pool tuning + role-aware connect + read-replica routing (`b.externalDb`); declarative role-narrowed views and Postgres row-level-security migrations (`b.db.declareView`, `b.db.declareRowPolicy`); S3 / R2 / B2 / GCS / Azure object store with multipart upload + SSE + bucket-ops (create / delete / list / lifecycle / CORS) across all three clouds, plus S3 Object Lock + per-object retention + legal hold for write-once-read-many compliance workloads (`b.storage`, `b.objectStore`); durable queue with priority + cron + flows on the local SQLite backend, a shared Redis backend, OR AWS SQS via SigV4 + AWSJsonProtocol_1.0 for fully-managed multi-replica deploys (`b.queue`, `b.jobs`); cluster-shared cache (`b.cache`).
+- **Identity & access** — passwords (Argon2id) + policy primitive (NIST 800-63B / PCI-DSS 4.0 / HIPAA-AAL2 profiles, HaveIBeenPwned k-anonymity breach check, length / context / dictionary / complexity rules, rotation + history) (`b.auth.password`); passkeys (WebAuthn), TOTP, JWT (PQ-default), OAuth + OIDC RP-Initiated / Front-Channel / Back-Channel Logout 1.0 (`b.auth.oauth.parseFrontchannelLogoutRequest` + `verifyBackchannelLogoutToken` with jti-replay defense), CIBA Core 1.0 decoupled-auth client (`b.auth.ciba`, poll/ping/push delivery, JWT-bearer / mTLS / shared-secret client auth), OpenID Federation 1.0 trust chain (`b.auth.openidFederation`, entity statement parse + verify, metadata_policy resolution), SAML 2.0 SP with XMLDSig signature-wrapping defense via single-match-by-ID invariant + RFC 9525 server-identity (`b.auth.saml`), OpenID4VCI 1.0 issuer (`b.auth.oid4vci` — credential_offer / pre-authorized_code / /credential with proof-JWT verification), OpenID4VP 1.0 verifier with DCQL query language (`b.auth.oid4vp`), SD-JWT VC with optional `key_attestation` extension for TEE / FIDO MDS3 / App Attest holder-key provenance (`b.auth.sdJwtVc`), sessions with PQC-sealed sid cookie (ML-KEM-1024 + P-384 hybrid + XChaCha20-Poly1305 envelope on the wire), `/24` IPv4 + `/64` IPv6 subnet binding via `fingerprintFields: ["clientIpPrefix"]` (carrier-roaming-safe), pluggable storage backend via `b.session.useStore` + first-party `b.session.stores.localDbThin` (tmpfs-fast session writes that don't fight the main DB's encrypted-at-rest re-flush cycle), opaque-userId anonymous sessions via `b.session.create({ anonymous: true })`, idle / absolute timeouts, optional fingerprint drift detection + anomaly scoring, brute-force lockout (`b.auth.*`, `b.session`); RBAC + optional per-role DB binding + role-spec `requireMfa` + per-route MFA freshness window + ABAC predicate registry (`b.permissions`); API keys with rotation (`b.apiKey`); break-glass column gates with second-factor + audit (`b.breakGlass`); two-person-rule approval workflow with m-of-n quorum + cooling-off lock + approver-role gate + cancellation (`b.dualControl`); FAPI 2.0 Final composite posture (PAR + PKCE-S256 + DPoP-or-mTLS sender-constrained tokens + RFC 9207 issuer-in-callback) for financial / Open Banking deployments (`b.fapi2`); CFPB §1033 / FDX 6.0 consumer-financial-data-sharing wrapper (`b.fdx`); cross-table data-subject coordination (export / rectify / erase / restrict / objection) walking every table tagged with the subject's column without app-side plumbing (`b.subject`, `b.subject.eraseHard`); subject-level legal-hold registry consulted by erase + retention paths (FRCP Rule 26/37(e), GDPR Art 17(3)(e), SEC Rule 17a-4, HIPAA §164.530(j)(2)) (`b.legalHold`); adaptive bot-challenge staircase composing `b.middleware.botGuard` + `b.auth.lockout` + operator challenge / escalation hooks for auth paths (`b.authBotChallenge`); session-to-device-posture binding (UA + Accept-Language + Accept-Encoding + IP /24 prefix + optional WebAuthn-bound key) with fail-closed verify on store error (`b.sessionDeviceBinding`).
 - **Crypto** — envelope-versioned PQC at rest (ML-KEM-1024 + P-384 hybrid, XChaCha20-Poly1305, SHAKE256), vault sealing, field-level crypto + cryptographic erasure (`b.cryptoField.eraseRow`), per-column data residency tagging + per-row keys (`K_row = HKDF(K_table, rowId)`) so erasing the per-row key makes WAL / replica residuals undecryptable — true crypto-shred discipline (`b.cryptoField.declareColumnResidency`, `b.cryptoField.declarePerRowKey`); AAD-bound sealed columns whose AEAD tag is tied to a `(table, rowId, column, schemaVersion)` tuple so a copy-paste between rows or a schema-version replay surfaces as a refused decrypt (`b.vault.aad`); signed webhooks (SLH-DSA-SHAKE-256f default; ML-DSA-65 opt-in for smaller signatures + faster verify), ECIES API encryption (`b.crypto`, `b.vault`, `b.webhook`); RFC 9180 HPKE with ML-KEM-1024 + HKDF-SHA3-512 + ChaCha20-Poly1305 suite (`b.crypto.hpke`); RFC 9421 HTTP Message Signatures with derived components (`@method`, `@target-uri`, `@authority`, `@path`, `@query`) and `created` / `expires` / `nonce` / `keyid` parameters; ed25519 (legacy peers) + ML-DSA-65 (PQC peers) (`b.crypto.httpSig`); RFC 9266 TLS-Exporter channel binding for token-to-session pinning (`b.tlsExporter`); RFC 9162 CT v2 inclusion-proof verification against signed tree heads (`b.network.tls.ct.verifyInclusion`); RFC 8555 ACME client + RFC 9773 ARI (Renewal Information) polling for the CA/Browser Forum 47-day certificate lifetime (`b.acme`); RFC 8470 0-RTT inbound posture (`refuse` default; `replay-cache` opt-in with 10s SHA3-512 dedupe window; fail-closed under `pci-dss` / `fapi2`) (`b.router.create({tls0Rtt})`); RFC 9794 SecP256r1MLKEM768 codepoint added to the preferred-group order (`b.network.tls.preferredGroups`); pure-JS mTLS CA that issues clientAuth / serverAuth / dual-EKU certs with SAN entries and auto-detects the highest-PQC signature algorithm the vendored x509 library accepts (today: ECDSA-P384-SHA384 bridge; self-upgrades to SLH-DSA / ML-DSA when the X.509 ecosystem catches up), PQC TLS gates inbound + outbound (`b.mtlsCa`, `b.pqcGate`, `b.pqcAgent`).
 - **HTTP** — router with schema-validated routes + OpenAPI publication (`b.openapi`) + AsyncAPI publication for event/streaming endpoints (`b.asyncapi`); full middleware stack (CSRF, CORS, rate-limit, security headers, CSP nonce, body parser, compression, SSE, request log, threat-aware cookie parser via `b.middleware.cookies`, request-time DB role binding via `b.middleware.dbRoleFor`, in-process CIDR fence via `b.middleware.networkAllowlist`) wired by `createApp`; HTTP/1.1 + HTTP/2 outbound client with SSRF gate (cloud-metadata IPs hard-denied unconditionally; private / loopback / link-local overridable per call), scheme + userinfo + per-host (wildcard / per-method) destination allowlist, redirects, multipart, interceptors, progress, encrypted cookie jar (`b.httpClient`, `b.ssrfGuard`, `b.safeUrl`); operator-tunable network configurability — env-driven NTP / NTS (RFC 8915 authenticated time), IPv4-or-IPv6 NTP servers, DNS with IPv6 / DoH / DoT (private-CA trust pinning via `opts.ca`) / cache / lookup timeout, outbound HTTP proxy (`HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY`), runtime DPI trust-store CA additions, application-level heartbeats, TCP socket defaults (`b.network`); operator-rendered error pages with no app-frame leakage (`b.errorPage`).
 - **Defensive parsers** — `b.safeJson` (with `maxKeys` cap defending CVE-2026-21717 V8 HashDoS), `b.safeBuffer`, `b.safeSql`, `b.safeSchema`, `b.safeUrl` (IDN mixed-script / homograph refuse), `b.safeJsonPath` (JSON-path validator refusing filter `?(...)`, deep-scan `$..`, script-shape `(@.x)` for safe Postgres JSONB ops), `b.parsers` (XML / TOML / YAML / .env), `b.config` (schema-validated env), `b.fileType` magic-byte content classification with deny-on-upload categories (image / document / archive / executable / etc.).

package/index.js

@@ -65,6 +65,11 @@ var vault = require("./lib/vault");
 var vaultWrap = require("./lib/vault/wrap");
 var vaultPassphraseSource = require("./lib/vault/passphrase-source");
 var db = require("./lib/db");
+// Standalone encrypted-DB-file lifecycle for consumers that own
+// their own SQLite handle. Attached as b.db.fileLifecycle so it
+// rides alongside the framework's full b.db API.
+db.fileLifecycle = require("./lib/db-file-lifecycle").fileLifecycle;
+var xmlC14n = require("./lib/xml-c14n");
 var cryptoField = require("./lib/crypto-field");
 var audit = require("./lib/audit");
 // Attach the audit-tools dispatcher onto b.audit so operators can
@@ -184,6 +189,11 @@ var auth = {
   authTime:   require("./lib/auth/auth-time-tracker"),
   accessLock: require("./lib/auth/access-lock"),
   atoKillSwitch: require("./lib/auth/ato-kill-switch"),
+  ciba:             require("./lib/auth/ciba"),
+  oid4vci:          require("./lib/auth/oid4vci"),
+  oid4vp:           require("./lib/auth/oid4vp"),
+  saml:             require("./lib/auth/saml"),
+  openidFederation: require("./lib/auth/openid-federation"),
 };
 var template = require("./lib/template");
 var render = require("./lib/render");
@@ -294,6 +304,7 @@ module.exports = {
   vaultWrap:        vaultWrap,
   vaultPassphraseSource: vaultPassphraseSource,
   db:               db,
+  xmlC14n:          xmlC14n,
   cryptoField:      cryptoField,
   audit:            audit,
   auditChain:       auditChain,

package/lib/audit.js

@@ -292,6 +292,7 @@ var FRAMEWORK_NAMESPACES = [
   "mailmdn",    // b.mailMdn (mailmdn.generated / mailmdn.suppressed — RFC 3798/8098 Message Disposition Notification)
   "mailarf",    // b.mailArf (mailarf.parsed / mailarf.malformed — RFC 5965 abuse-feedback ingestion)
   "mailbimi",   // b.mail.bimi (mail.bimi.vmc.fetched / verified — RFC 9091 VMC chain validation)
+  "localdb",    // b.localDb.thin (localdb.thin.opened / recovered / closed — desktop-daemon SQLite wrapper)
 ];
 var registeredNamespaces = new Set(FRAMEWORK_NAMESPACES);
 

package/lib/auth/ciba.js

@@ -0,0 +1,530 @@
+"use strict";
+/**
+ * @module     b.auth.ciba
+ * @nav        Identity
+ * @title      CIBA (decoupled auth)
+ * @order      330
+ * @card       OpenID Connect Client-Initiated Backchannel Authentication
+ *             1.0 — the "decoupled" auth flow where the relying party
+ *             authenticates the user out-of-band (push notification to a
+ *             phone, kiosk-driven sign-in on a separate channel) and
+ *             tokens are delivered via poll / ping / push.
+ *
+ * @intro
+ *   CIBA is the OpenID Connect spec for flows where the device that
+ *   initiates the authentication isn't the device that completes it.
+ *   Canonical use cases: a call-center agent confirming a customer
+ *   identity by pushing a prompt to the customer's phone; a TPM-less
+ *   POS terminal asking the user's wallet to authorize a purchase; an
+ *   IVR step-up that requires the customer's mobile-app fingerprint.
+ *
+ *   The relying party (RP):
+ *     1. POSTs `auth_req_id` request to the IdP's
+ *        `backchannel_authentication_endpoint` with login_hint /
+ *        login_hint_token / id_token_hint identifying the user, plus
+ *        scope / acr_values / requested_expiry / binding_message.
+ *     2. Receives `{ auth_req_id, expires_in, interval }`.
+ *     3. Waits for token delivery via the operator-chosen mode:
+ *
+ *        - **poll**: RP polls /token with grant_type=
+ *          urn:openid:params:grant-type:ciba + auth_req_id every
+ *          `interval` seconds; gets `authorization_pending`,
+ *          `slow_down`, or the tokens.
+ *        - **ping**: IdP POSTs `{ auth_req_id }` to the RP's
+ *          `client_notification_endpoint`; the RP's handler then
+ *          calls /token to fetch.
+ *        - **push**: IdP POSTs `{ auth_req_id, access_token,
+ *          id_token, refresh_token, ... }` directly. The
+ *          `client_notification_token` registered with the IdP
+ *          authenticates each callback.
+ *
+ *   This module provides:
+ *
+ *     b.auth.ciba.client.create({ ... })
+ *       .startAuthentication({ loginHint, scope, bindingMessage, ... })
+ *       .pollToken({ authReqId })
+ *       .receivePingNotification(req)        // ping mode handler
+ *       .receivePushNotification(req)        // push mode handler
+ *
+ *   Composes b.auth.oauth for client_assertion / token-endpoint
+ *   plumbing (so JWT-bearer client auth, mTLS client auth, and PAR
+ *   alongside CIBA all share one set of audited credentials).
+ */
+
+var lazyRequire  = require("../lazy-require");
+var validateOpts = require("../validate-opts");
+var safeJson     = require("../safe-json");
+var safeUrl      = require("../safe-url");
+var { generateToken, sha3Hash } = require("../crypto");
+var { AuthError } = require("../framework-error");
+
+var httpClient    = lazyRequire(function () { return require("../http-client"); });
+var oauth         = lazyRequire(function () { return require("./oauth"); });
+var audit         = lazyRequire(function () { return require("../audit"); });
+var observability = lazyRequire(function () { return require("../observability"); });
+var emit = validateOpts.makeNamespacedEmitters("auth.ciba", { audit: audit, observability: observability });
+
+var DEFAULT_INTERVAL_SEC = 5;
+var DEFAULT_EXPIRES_SEC  = 600;
+var MAX_BINDING_MSG_LEN  = 200;
+var MAX_RESPONSE_BYTES   = 64 * 1024;                                                            // allow:raw-byte-literal — JSON token-response cap
+var MIN_INTERVAL_SEC     = 1;
+var MAX_INTERVAL_SEC     = 300;                                                                  // allow:raw-time-literal — interval ceiling
+
+// _emitAudit emits under the "auth.ciba.<action>" namespace; _emitMetric
+// fires the matching observability counter. Implementations live in
+// validateOpts.makeNamespacedEmitters; the locals are aliases so the
+// existing call sites read identically.
+var _emitAudit  = emit.audit;
+var _emitMetric = emit.metric;
+
+/**
+ * @primitive b.auth.ciba.client.create
+ * @signature b.auth.ciba.client.create(opts)
+ * @since     0.8.62
+ * @status    stable
+ * @related   b.auth.oid4vci.issuer.create
+ *
+ * Build a CIBA-aware OIDC RP. Operators wire the resulting object's
+ * methods onto routes that drive the decoupled-auth flow.
+ *
+ * @opts
+ *   {
+ *     issuer:                     string,        // OIDC issuer URL — required
+ *     clientId:                   string,        // RP client_id — required
+ *     clientAuth:                 "secret"|"jwt"|"mtls",   // token-endpoint auth
+ *     clientSecret?:              string,        // when clientAuth = "secret"
+ *     clientAssertionSigner?:     fn(payload)→jwt, // when clientAuth = "jwt"
+ *     backchannelAuthenticationEndpoint?: string, // optional — discovered when omitted
+ *     tokenEndpoint?:             string,        // optional — discovered
+ *     scope?:                     string|string[],
+ *     deliveryMode:               "poll"|"ping"|"push",
+ *     clientNotificationToken?:   string,        // fixed token RP mints once + registers with IdP
+ *     httpClientOpts?:            object,
+ *     allowHttp?:                 boolean,
+ *   }
+ *
+ * @example
+ *   var ciba = b.auth.ciba.client.create({
+ *     issuer:       "https://idp.example.com",
+ *     clientId:     "rp-1",
+ *     clientAuth:   "secret",
+ *     clientSecret: process.env.CIBA_CLIENT_SECRET,
+ *     scope:        ["openid", "profile"],
+ *     deliveryMode: "poll",
+ *   });
+ *   var ticket = await ciba.startAuthentication({
+ *     loginHint:      "alice@example.com",
+ *     bindingMessage: "Authorize wire transfer of $4,200",
+ *     acrValues:      ["urn:mace:incommon:iap:silver"],
+ *   });
+ *   // → { authReqId, expiresIn, interval }
+ *   var tokens = await ciba.pollToken({ authReqId: ticket.authReqId });
+ *   // → { accessToken, idToken, ... } once user approves
+ */
+function create(opts) {
+  validateOpts.requireObject(opts, "auth.ciba.client.create", AuthError);
+  validateOpts.requireNonEmptyString(opts.issuer, "auth.ciba.client.create: issuer", AuthError, "auth-ciba/no-issuer");
+  validateOpts.requireNonEmptyString(opts.clientId, "auth.ciba.client.create: clientId", AuthError, "auth-ciba/no-client-id");
+
+  var clientAuth = opts.clientAuth || "secret";
+  if (["secret", "jwt", "mtls"].indexOf(clientAuth) === -1) {
+    throw new AuthError("auth-ciba/bad-client-auth",
+      "auth.ciba.client.create: clientAuth must be 'secret' | 'jwt' | 'mtls'");
+  }
+  if (clientAuth === "secret" && !opts.clientSecret) {
+    throw new AuthError("auth-ciba/no-client-secret",
+      "auth.ciba.client.create: clientSecret required for clientAuth='secret'");
+  }
+  if (clientAuth === "jwt" && typeof opts.clientAssertionSigner !== "function") {
+    throw new AuthError("auth-ciba/no-assertion-signer",
+      "auth.ciba.client.create: clientAssertionSigner required for clientAuth='jwt'");
+  }
+
+  var deliveryMode = opts.deliveryMode || "poll";
+  if (["poll", "ping", "push"].indexOf(deliveryMode) === -1) {
+    throw new AuthError("auth-ciba/bad-delivery-mode",
+      "auth.ciba.client.create: deliveryMode must be 'poll' | 'ping' | 'push'");
+  }
+
+  // Inner OAuth client — composes discovery, JWKS fetch, ID-token
+  // verification. CIBA's token endpoint, JWKS, and discovery are all
+  // shared with the RP's other OIDC flows so we reuse the existing
+  // primitive's caching + audit + clock-skew tolerance.
+  var inner = oauth().create({
+    issuer:                            opts.issuer,
+    clientId:                          opts.clientId,
+    clientSecret:                      opts.clientSecret,
+    redirectUri:                       opts.redirectUri || (opts.issuer + "/__ciba_no_redirect__"),
+    scope:                             opts.scope,
+    backchannelAuthenticationEndpoint: opts.backchannelAuthenticationEndpoint,
+    tokenEndpoint:                     opts.tokenEndpoint,
+    httpClientOpts:                    opts.httpClientOpts,
+    allowHttp:                         opts.allowHttp === true,
+    isOidc:                            true,
+  });
+
+  var clientNotificationToken = opts.clientNotificationToken || null;
+  if ((deliveryMode === "ping" || deliveryMode === "push") && !clientNotificationToken) {
+    throw new AuthError("auth-ciba/no-notification-token",
+      "auth.ciba.client.create: clientNotificationToken required for ping/push delivery modes");
+  }
+
+  // Each backchannel-authentication request mints a fresh
+  // `client_notification_token` per the spec? No — the RP registers
+  // ONE long-lived token with the IdP at registration time. Operator
+  // rotates by re-registering. Per CIBA §7.1.1.
+
+  function _basicAuthHeader() {
+    if (clientAuth !== "secret") return null;
+    var pair = opts.clientId + ":" + opts.clientSecret;
+    return "Basic " + Buffer.from(pair, "utf8").toString("base64");
+  }
+
+  async function _resolveBackchannelEndpoint() {
+    // Hit discovery if not pre-configured. The inner OAuth client
+    // already has discovery cache; we ride it via the public discover()
+    // shape.
+    if (opts.backchannelAuthenticationEndpoint) return opts.backchannelAuthenticationEndpoint;
+    var disc = await inner.discover();
+    if (!disc || typeof disc.backchannel_authentication_endpoint !== "string") {
+      throw new AuthError("auth-ciba/no-backchannel-endpoint",
+        "ciba: IdP discovery doc has no backchannel_authentication_endpoint " +
+        "(set opts.backchannelAuthenticationEndpoint on create() if the IdP doesn't publish it)");
+    }
+    return disc.backchannel_authentication_endpoint;
+  }
+
+  async function _resolveTokenEndpoint() {
+    if (opts.tokenEndpoint) return opts.tokenEndpoint;
+    var disc = await inner.discover();
+    if (!disc || typeof disc.token_endpoint !== "string") {
+      throw new AuthError("auth-ciba/no-token-endpoint",
+        "ciba: IdP discovery doc has no token_endpoint");
+    }
+    return disc.token_endpoint;
+  }
+
+  function _validateBindingMessage(msg) {
+    if (msg === undefined || msg === null) return null;
+    if (typeof msg !== "string") {
+      throw new AuthError("auth-ciba/bad-binding-message",
+        "ciba: bindingMessage must be a string");
+    }
+    if (msg.length > MAX_BINDING_MSG_LEN) {
+      throw new AuthError("auth-ciba/binding-message-too-long",
+        "ciba: bindingMessage exceeds " + MAX_BINDING_MSG_LEN + " chars (CIBA §7.1)");
+    }
+    // Per §7.1, binding_message MUST be plain text + restricted to
+    // characters most user-agents render legibly. Refuse control /
+    // bidi / zero-width.
+    // Codepoint scan instead of a regex character class - eslint's
+    // no-control-regex rule refuses control-char ranges in regex
+    // literals regardless of how they're spelled.
+    for (var ci = 0; ci < msg.length; ci += 1) {
+      var cc = msg.charCodeAt(ci);
+      if (cc <= 0x001f ||
+          (cc >= 0x007f && cc <= 0x009f) ||
+          (cc >= 0x200b && cc <= 0x200f) ||
+          (cc >= 0x202a && cc <= 0x202e) ||
+          (cc >= 0x2066 && cc <= 0x2069) ||
+          cc === 0xfeff) {                                                                      // allow:raw-byte-literal — codepoint constants for control / bidi / zero-width / BOM
+        throw new AuthError("auth-ciba/binding-message-control-chars",
+          "ciba: bindingMessage contains control / bidi / zero-width characters");
+      }
+    }
+    return msg;
+  }
+
+  async function _postForm(url, body, headers) {
+    safeUrl.assertHttpUrl(url, opts.allowHttp === true);
+    var hc = httpClient();
+    var basic = _basicAuthHeader();
+    var hdrs = Object.assign({
+      "Content-Type": "application/x-www-form-urlencoded",
+      "Accept":       "application/json",
+    }, headers || {});
+    if (basic) hdrs["Authorization"] = basic;
+    var req = {
+      url:    url,
+      method: "POST",
+      headers: hdrs,
+      body:    body.toString(),
+    };
+    Object.assign(req, opts.httpClientOpts || {});
+    if (opts.allowHttp === true) req.allowedProtocols = safeUrl.ALLOW_HTTP_ALL;
+    var res = await hc.request(req);
+    if (res.statusCode < 200 || res.statusCode >= 300) {
+      var bodyText = res.body ? res.body.toString("utf8") : "";
+      var err;
+      try { err = safeJson.parse(bodyText, { maxBytes: MAX_RESPONSE_BYTES }); } catch (_e) { /* silent-catch: non-JSON IdP error body falls through to the bodyText snippet path below */ }
+      var code = (err && err.error) || ("http-" + res.statusCode);
+      var msg = (err && (err.error_description || err.error)) || bodyText.slice(0, 200);   // allow:raw-byte-literal — error-message snippet length
+      var aerr = new AuthError("auth-ciba/" + code, "ciba: " + msg);
+      aerr.cibaError = err || null;
+      aerr.statusCode = res.statusCode;
+      throw aerr;
+    }
+    if (!res.body) return null;
+    try { return safeJson.parse(res.body.toString("utf8"), { maxBytes: MAX_RESPONSE_BYTES }); }
+    catch (e) {
+      throw new AuthError("auth-ciba/bad-json",
+        "ciba: response not JSON: " + ((e && e.message) || String(e)));
+    }
+  }
+
+  /**
+   * @primitive b.auth.ciba.client.startAuthentication
+   * @signature b.auth.ciba.client.startAuthentication(opts)
+   * @since     0.8.62
+   *
+   * POST to the IdP's backchannel_authentication_endpoint and return
+   * a ticket with `authReqId` + `expiresIn` + `interval`. At least
+   * one of `loginHint` / `loginHintToken` / `idTokenHint` must be
+   * supplied to identify the user.
+   *
+   * @opts
+   *   {
+   *     loginHint?:        string,
+   *     loginHintToken?:   string,
+   *     idTokenHint?:      string,
+   *     scope?:            string|string[],
+   *     bindingMessage?:   string,
+   *     acrValues?:        string|string[],
+   *     requestedExpiry?:  number,
+   *     userCode?:         string,
+   *   }
+   *
+   * @example
+   *   var ticket = await ciba.startAuthentication({
+   *     loginHint:      "alice@example.com",
+   *     bindingMessage: "Authorize wire transfer of $4,200",
+   *   });
+   *   // → { authReqId, expiresIn, interval }
+   */
+  async function startAuthentication(sopts) {
+    sopts = sopts || {};
+    if (!sopts.loginHint && !sopts.loginHintToken && !sopts.idTokenHint) {
+      throw new AuthError("auth-ciba/no-user-hint",
+        "ciba.startAuthentication: one of loginHint / loginHintToken / idTokenHint required");
+    }
+    var endpoint = await _resolveBackchannelEndpoint();
+    var body = new URLSearchParams();
+    if (sopts.loginHint)      body.set("login_hint", sopts.loginHint);
+    if (sopts.loginHintToken) body.set("login_hint_token", sopts.loginHintToken);
+    if (sopts.idTokenHint)    body.set("id_token_hint", sopts.idTokenHint);
+
+    var scope = sopts.scope || opts.scope || ["openid"];
+    if (Array.isArray(scope)) scope = scope.join(" ");
+    body.set("scope", scope);
+
+    if (sopts.bindingMessage !== undefined) {
+      var msg = _validateBindingMessage(sopts.bindingMessage);
+      if (msg) body.set("binding_message", msg);
+    }
+    if (Array.isArray(sopts.acrValues) && sopts.acrValues.length > 0) {
+      body.set("acr_values", sopts.acrValues.join(" "));
+    } else if (typeof sopts.acrValues === "string" && sopts.acrValues.length > 0) {
+      body.set("acr_values", sopts.acrValues);
+    }
+    if (typeof sopts.requestedExpiry === "number" &&
+        Number.isInteger(sopts.requestedExpiry) && sopts.requestedExpiry > 0) {
+      body.set("requested_expiry", String(sopts.requestedExpiry));
+    }
+    if (typeof sopts.userCode === "string") body.set("user_code", sopts.userCode);
+
+    if (clientAuth === "jwt") {
+      var assertion = await opts.clientAssertionSigner({
+        iss: opts.clientId, sub: opts.clientId, aud: endpoint,
+        iat: Math.floor(Date.now() / 1000),                                                     // allow:raw-byte-literal — ms→s
+        exp: Math.floor(Date.now() / 1000) + 300,                                               // allow:raw-byte-literal — assertion 5m TTL
+        jti: generateToken(16),
+      });
+      body.set("client_assertion_type", "urn:ietf:params:oauth:client-assertion-type:jwt-bearer");
+      body.set("client_assertion", assertion);
+      body.set("client_id", opts.clientId);
+    }
+    if (clientAuth === "mtls") {
+      body.set("client_id", opts.clientId);
+    }
+    if (clientNotificationToken && (deliveryMode === "ping" || deliveryMode === "push")) {
+      body.set("client_notification_token", clientNotificationToken);
+    }
+
+    var rv = await _postForm(endpoint, body);
+    if (!rv || typeof rv.auth_req_id !== "string") {
+      throw new AuthError("auth-ciba/bad-response",
+        "ciba.startAuthentication: response missing auth_req_id");
+    }
+    var interval = typeof rv.interval === "number" && rv.interval >= MIN_INTERVAL_SEC && rv.interval <= MAX_INTERVAL_SEC
+      ? rv.interval : DEFAULT_INTERVAL_SEC;
+    var expiresIn = typeof rv.expires_in === "number" && rv.expires_in > 0
+      ? rv.expires_in : DEFAULT_EXPIRES_SEC;
+
+    _emitAudit("start", "success", {
+      authReqIdHash: sha3Hash("auth-ciba:" + rv.auth_req_id),
+      deliveryMode:  deliveryMode,
+      hasBindingMessage: !!sopts.bindingMessage,
+    });
+    _emitMetric("started");
+    return {
+      authReqId: rv.auth_req_id,
+      expiresIn: expiresIn,
+      interval:  interval,
+    };
+  }
+
+  /**
+   * @primitive b.auth.ciba.client.pollToken
+   * @signature b.auth.ciba.client.pollToken(opts)
+   * @since     0.8.62
+   *
+   * Poll the IdP's /token endpoint with grant_type=ciba. Returns the
+   * tokens once the user approves; throws AuthError with code
+   * "auth-ciba/authorization_pending" or "auth-ciba/slow_down" while
+   * waiting. Operators wrap with their preferred backoff.
+   *
+   * @opts
+   *   { authReqId: string }
+   *
+   * @example
+   *   var tokens = await ciba.pollToken({ authReqId: ticket.authReqId });
+   *   // → { accessToken, idToken, refreshToken, tokenType, scope, expiresIn, raw }
+   */
+  async function pollToken(popts) {
+    popts = popts || {};
+    if (typeof popts.authReqId !== "string" || popts.authReqId.length === 0) {
+      throw new AuthError("auth-ciba/no-auth-req-id",
+        "ciba.pollToken: authReqId required");
+    }
+    var endpoint = await _resolveTokenEndpoint();
+    var body = new URLSearchParams();
+    body.set("grant_type", "urn:openid:params:grant-type:ciba");
+    body.set("auth_req_id", popts.authReqId);
+    if (clientAuth === "jwt") {
+      var assertion = await opts.clientAssertionSigner({
+        iss: opts.clientId, sub: opts.clientId, aud: endpoint,
+        iat: Math.floor(Date.now() / 1000),                                                     // allow:raw-byte-literal — ms→s
+        exp: Math.floor(Date.now() / 1000) + 300,                                               // allow:raw-byte-literal — assertion 5m TTL
+        jti: generateToken(16),
+      });
+      body.set("client_assertion_type", "urn:ietf:params:oauth:client-assertion-type:jwt-bearer");
+      body.set("client_assertion", assertion);
+      body.set("client_id", opts.clientId);
+    }
+    if (clientAuth === "mtls") body.set("client_id", opts.clientId);
+    var rv = await _postForm(endpoint, body);
+    _emitAudit("token_received", "success", {
+      authReqIdHash: sha3Hash("auth-ciba:" + popts.authReqId),
+    });
+    _emitMetric("token-received");
+    return {
+      accessToken:  rv.access_token   || null,
+      idToken:      rv.id_token       || null,
+      refreshToken: rv.refresh_token  || null,
+      tokenType:    rv.token_type     || null,
+      scope:        rv.scope          || null,
+      expiresIn:    typeof rv.expires_in === "number" ? rv.expires_in : null,
+      raw:          rv,
+    };
+  }
+
+  /**
+   * @primitive b.auth.ciba.client.parseNotification
+   * @signature b.auth.ciba.client.parseNotification(req, opts)
+   * @since     0.8.62
+   *
+   * Parse + authenticate an IdP-initiated callback to the RP's
+   * `client_notification_endpoint`. Validates the bearer
+   * `client_notification_token` (timing-safe equality) before
+   * surfacing the body. Use the returned `authReqId` to drive the
+   * RP-side flow:
+   *
+   *   - In **ping** mode the body is `{ auth_req_id }`. Call
+   *     `pollToken({ authReqId })` afterwards.
+   *   - In **push** mode the body carries the full token-response
+   *     object; no follow-up call needed.
+   *
+   * @opts
+   *   { body?: object }   // pre-parsed body; defaults to req.body
+   *
+   * @example
+   *   app.post("/ciba/notify", function (req, res) {
+   *     var info = ciba.parseNotification(req, { body: req.body });
+   *     // → { authReqId, accessToken, idToken, ... }
+   *     res.statusCode = 204; res.end();
+   *   });
+   */
+  function parseNotification(req, popts) {
+    popts = popts || {};
+    if (!req || !req.headers) {
+      throw new AuthError("auth-ciba/bad-notification-req",
+        "ciba.parseNotification: req with headers required");
+    }
+    var authzHeader = req.headers["authorization"] || req.headers["Authorization"];
+    if (!authzHeader || authzHeader.indexOf("Bearer ") !== 0) {
+      throw new AuthError("auth-ciba/missing-bearer",
+        "ciba.parseNotification: Authorization: Bearer header missing");
+    }
+    var presented = authzHeader.substring("Bearer ".length).trim();
+    if (presented.length === 0 || !clientNotificationToken) {
+      throw new AuthError("auth-ciba/bad-bearer",
+        "ciba.parseNotification: empty bearer or no expected token configured");
+    }
+    // Constant-time compare via the framework's primitive shape —
+    // sha3-of-each + ===-of-hash is constant-time over equal-length
+    // hashes regardless of presented length, so a length-side-channel
+    // probe can't enumerate the prefix.
+    var presentedHash = sha3Hash(presented);
+    var expectedHash  = sha3Hash(clientNotificationToken);
+    if (presentedHash !== expectedHash) {
+      _emitAudit("notification_token_mismatch", "failure", {});
+      throw new AuthError("auth-ciba/wrong-bearer",
+        "ciba.parseNotification: client_notification_token does not match");
+    }
+    var body = popts.body !== undefined ? popts.body : req.body;
+    if (typeof body === "string") {
+      try { body = safeJson.parse(body, { maxBytes: MAX_RESPONSE_BYTES }); }
+      catch (e) {
+        throw new AuthError("auth-ciba/bad-notification-body",
+          "ciba.parseNotification: body is not JSON: " + ((e && e.message) || String(e)));
+      }
+    }
+    if (!body || typeof body !== "object") {
+      throw new AuthError("auth-ciba/no-notification-body",
+        "ciba.parseNotification: body required (Buffer/string parsed by middleware)");
+    }
+    if (typeof body.auth_req_id !== "string") {
+      throw new AuthError("auth-ciba/no-auth-req-id-in-body",
+        "ciba.parseNotification: body missing auth_req_id");
+    }
+    _emitAudit("notification_received", "success", {
+      authReqIdHash: sha3Hash("auth-ciba:" + body.auth_req_id),
+      mode:          deliveryMode,
+    });
+    _emitMetric("notification-received");
+    return {
+      authReqId:    body.auth_req_id,
+      accessToken:  body.access_token  || null,
+      idToken:      body.id_token      || null,
+      refreshToken: body.refresh_token || null,
+      tokenType:    body.token_type    || null,
+      scope:        body.scope         || null,
+      expiresIn:    typeof body.expires_in === "number" ? body.expires_in : null,
+      raw:          body,
+    };
+  }
+
+  return {
+    startAuthentication: startAuthentication,
+    pollToken:           pollToken,
+    parseNotification:   parseNotification,
+    issuer:              opts.issuer,
+    clientId:            opts.clientId,
+    deliveryMode:        deliveryMode,
+  };
+}
+
+module.exports = {
+  client: { create: create },
+};