@blamejs/core 0.14.17 → 0.14.19

package/CHANGELOG.md

@@ -8,6 +8,10 @@ upgrading across more than a few patches at a time.
 
 ## v0.14.x
 
+- v0.14.19 (2026-06-02) — **ZIP64 write completes large-archive support, plus a PKCE-downgrade defense, SCIM Bulk, OID4VCI kid-resolution, SPF macros, DMARC report building, and OpenAPI 3.2.** This release fills out several standards the framework previously read but could not write, or advertised but did not fully implement. The ZIP writer now emits ZIP64, so archives larger than 65535 entries or 4 GiB are produced instead of refused (the reader gained ZIP64 in the previous release; the two now round-trip). The OAuth client refuses an OP whose discovery metadata advertises PKCE methods without S256 — closing a stripped-S256 downgrade. The SCIM server gains opt-in Bulk operations, the OID4VCI issuer accepts a kid-resolution hook for EUDI-Wallet attested-key proofs (and a latent cache-cleanup crash on the issuance path is fixed), the inbound SPF check expands RFC 7208 macros and evaluates the exists mechanism, a DMARC aggregate-report builder is the inverse of the existing parser, and the OpenAPI emitter supports 3.2 with webhooks and a JSON Schema dialect. Every behavior-changing addition is opt-in or additive: classic archives emit byte-for-byte unchanged, OpenAPI still defaults to 3.1.0, SCIM Bulk stays disabled unless configured, and the PKCE refusal only fires for an OP that explicitly advertises a non-S256 method set. **Added:** *`b.archive.zip` writes ZIP64* — When an archive exceeds 65535 entries, or any entry's compressed/uncompressed size or local-header offset exceeds 4 GiB, the writer now emits ZIP64 — the classic field carries the `0xFFFF`/`0xFFFFFFFF` sentinel and a ZIP64 extended-information extra field (header id `0x0001`) plus a ZIP64 EOCD record and locator are written (APPNOTE 6.3.10 §4.3.14 / §4.3.15 / §4.4.8 / §4.5.3). Archives within the classic limits emit byte-for-byte unchanged, and `b.archive.read.zip` reads the ZIP64 output transparently. Previously the writer refused past 65535 entries. · *`b.middleware.scimServer` opt-in SCIM 2.0 Bulk operations* — A `/Bulk` POST endpoint (RFC 7644 §3.7) with `maxOperations` / `maxPayloadSize` caps, `bulkId` cross-reference resolution (§3.7.2), and `failOnErrors` short-circuiting, advertised in `ServiceProviderConfig` when enabled via `opts.bulk`. The request body is read through the bounded stream reader. Bulk stays disabled (and `/Bulk` returns 501) unless `opts.bulk` is set. · *`b.auth.oid4vci` accepts a `resolveKid` proof-key hook* — An OID4VCI proof JWT that carries a header `kid` without an inline `jwk` (the EUDI-Wallet attested-key shape) can now be verified by supplying `create({ resolveKid(kid, header) })`, which maps the key id to a holder key. The resolved key passes the same alg/key-type cross-check (CVE-2026-22817) as the inline path before import and becomes the credential's `cnf` binding. Without a resolver, a kid-only proof is still refused, exactly as before. · *SPF macro expansion + `exists`; DMARC aggregate-report builder* — `b.mail.spf.verify` now expands RFC 7208 §7 macros (`%{i}`/`%{s}`/`%{l}`/`%{d}`/`%{o}`/`%{h}`/`%{v}` with the reverse / digit-count / delimiter transformers and `%%`/`%_`/`%-` escapes) and evaluates the `exists` mechanism (§5.7); the §4.6.4 DNS-lookup and void-lookup ceilings still bound every macro-driven query. New `b.mail.dmarc.buildAggregateReport` serializes a DMARC aggregate (RUA) report to RFC 7489 Appendix C XML — the inverse of `parseAggregateReport` — with optional gzip and XML-metacharacter escaping of observed identifiers. · *OpenAPI 3.2 — webhooks and `jsonSchemaDialect`* — `b.openapi.create({ openapi: "3.2.0" })` opts into OpenAPI 3.2; a `webhook(name, method, opts)` builder registers top-level `webhooks` (API-initiated out-of-band operations), and `jsonSchemaDialect` declares the document's default JSON Schema dialect. `parse()` accepts 3.1.x or 3.2.x and validates webhook operations (including dangling-security references) with the same rules as paths. 3.1.0 stays the default emitted version and existing 3.1 documents are unchanged. **Fixed:** *OID4VCI issuance crashed on cache cleanup* — The pre-authorized-code exchange and credential-issuance paths called `.delete()` on their internal `b.cache` stores, which expose `del()` — so the cleanup step threw and the issuance flow could not complete end-to-end. The three call sites now use `del()`. **Security:** *PKCE-downgrade defense for OAuth / OIDC clients* — The OAuth client already mandates PKCE-S256 on its own side but never inspected the OP's published `code_challenge_methods_supported`. It now refuses, at `authorizationUrl` / `pushAuthorizationRequest`, an OP whose discovery metadata advertises that field without `"S256"` (plain-only / empty) — blocking a stripped-S256 downgrade that would otherwise drive the client into an authorization request the OP claims it cannot verify (RFC 9700 §4.13, RFC 7636). An OP that does not publish the field, and static-endpoint clients that perform no discovery, are unaffected. **Migration:** *No action required; additions are additive or opt-in* — ZIP64 write is additive — archives within the classic 65535-entry / 4 GiB limits emit identical bytes, and the writer simply no longer refuses larger ones. SCIM Bulk, the OID4VCI `resolveKid` hook, the DMARC report builder, and OpenAPI 3.2 are all opt-in (OpenAPI still defaults to 3.1.0). The SPF `exists` mechanism, previously returning permerror, now evaluates per RFC 7208 — `b.mail.spf.verify` returns a verdict and refuses nothing. The PKCE-downgrade refusal only fires for an OP that explicitly advertises a non-S256 PKCE method set.
+
+- v0.14.18 (2026-06-01) — **Advertised endpoints that silently failed now work, plus opt-in response-shaping, transport hardening, and ZIP64 read.** This release closes a set of advertised-but-broken surfaces and adds the extensibility hooks operators kept having to work around. Three endpoints silently failed: the CSP-report endpoint returned 413 to every POST (it never parsed a report), the SCIM server broke on any streamed request body, and both came from misusing the bounded-buffer collector as if it consumed a stream — so this release adds the missing b.safeBuffer.collectStream(stream, opts) primitive and routes both through it. The agent orchestrator's graceful-drain phase never registered (wrong method name), the OpenAPI/AsyncAPI doc endpoints ignored a documented single-origin CORS allowlist, and the EU AI Act Article 50 HTML banner skipped Buffer response bodies. Deny-path refusals gained an RFC 9457 problem-type derived from the problem code (a 429 read about:blank before) and now treat a consumer hook that commits headers as terminal. On top of the fixes, several middlewares gain operator hooks (custom JSON/HTML error formatters, problem+json, refusal callbacks), several entry points gain escape-hatch opts (a configurable Authorization scheme, legacy filename charsets, a submission relay port, an exit-after-phases shutdown), the local job queue can point at an operator-supplied database/table/schema, breach-notification deadlines gain a running escalation clock, the archive reader now reads ZIP64, and external databases gain an opt-in TLS-required posture plus OpenTelemetry db.* trace attributes. Every behavior-changing addition is strictly opt-in — an operator who sets no new option sees no change. **Added:** *`b.safeBuffer.collectStream(stream, opts)` — bounded stream-to-Buffer reader* — Reads a Node Readable (a request body, an upstream response) fully into one Buffer with the byte cap enforced at every chunk — the streaming sibling of `boundedChunkCollector`, which is a push-collector, not a stream consumer. Resolves the concatenated Buffer on end; rejects (and destroys the stream) the moment a chunk would overflow `maxBytes`. · *Operator response-shaping hooks* — `b.errorPage` gains `jsonFormatter(info, req)` and `renderHtml(info, req)` overrides plus a `problemDetails: true` RFC 9457 mode (each falls back to the built-in envelope on throw, so the original error is never masked); `b.render.json` gains an `opts.replacer` passthrough (BigInt/Date); `b.middleware.cspReport` gains `onReject(req, res, { status, reason })` for the otherwise-empty-bodied 405/413/400 refusals; `b.static` gains `onError` firing on every refusal path, mirroring `onServe`. · *Escape-hatch opts for non-default deployments* — `b.appShutdown.create({ exitAfterPhases })` lets a manual `shutdown()` exit after its phases (not only a signal-driven shutdown); `b.middleware.attachUser({ bearerScheme, tokenExtractor })` reads `Token`/`DPoP`/gateway Authorization schemes (RFC 6750 / RFC 9449); `b.middleware.bodyParser` multipart `filenameCharsets` opts iso-8859-1 `filename*` decoding in (RFC 5987); `b.mail.send.deliver.create({ port })` routes through a 587/465 submission relay (RFC 6409 / RFC 8314). · *Local job queue: bring-your-own database, table, and schema* — `b.queue.init` local-backend config accepts `db` (an operator-supplied handle), `table`, and `schema`. Table and schema names are validated and quoted as SQL identifiers (refused at init time when unsafe); the sealed `payload`/`lastError` columns stay sealed regardless of the physical table. Defaults are unchanged (`_blamejs_jobs` on the framework/cluster database). · *`b.breach.deadline.createClock` — running breach-notification escalation clock* — A detection-to-notification clock that escalates each affected US state's statutory breach-notification deadline (an approaching warning, a passed alert) and accepts per-state filing acknowledgements, complementing the existing static deadline lookup. It composes the incident-report deadline clock, so there is a single timer to start and stop. · *`b.archive.read.zip` reads ZIP64* — Archives with more than 65535 entries or with sizes/offsets past 4 GiB now decode transparently (APPNOTE 6.3.10 §4.3.14 / §4.3.15 / §4.5.3). Previously such archives were refused outright. The bomb, Zip-Slip, PATH_MAX, and entry-type defenses all continue to apply to the resolved 64-bit values. · *External-database opt-in TLS posture and OpenTelemetry `db.*` traces* — `b.externalDb` backends accept `requireTls: true` (default off), which refuses a backend at config time unless its declared transport is TLS (`tls` / a truthy `ssl` / `sslmode` `require|verify-ca|verify-full`) — for cardholder data or ePHI (PCI-DSS v4.0 Req 4 / HIPAA §164.312(e)). Query/transaction/read traces now also carry OpenTelemetry database semantic-convention attributes (`db.system`, `db.operation`, `db.statement` (sanitized), `db.name`). · *Opt-in schema-drift detection* — `b.db.init({ onDrift })` (and the underlying `reconcile({ onDrift })`) opts into config-vs-live column-drift detection: `"warn"` reports columns present in the live database but absent from the declared schema; `"refuse"` makes the framework refuse to boot on drift (a strict-schema posture — ISO 27001:2022 A.8.9 / SOC 2 CC8.1). The default (`"ignore"`) is unchanged, and drift is never resolved destructively. **Changed:** *`b.guardEmail` documents its actual Unicode scope* — Domain-side IDN/Punycode and mixed-script confusable detection are supported (and unchanged); the local-part is ASCII atext only (RFC 5321/5322). The documentation previously implied RFC 6531 SMTPUTF8/EAI mailbox names were accepted — they are rejected by default, re-openable behind a future `allowUnicodeLocalPart` opt-in, to keep homograph/confusable exposure bounded to the domain side. No validation behavior changed. · *Body-parse 4xx responses send `Connection: close`* — Every body-parse rejection (malformed JSON, poisoned key, oversized payload, bad content-length) now closes the connection, matching the chunked-decode path, to deny an upstream proxy reusing a socket whose request stream the parser abandoned mid-body (RFC 9112 §9.6). · *Archive-reader default entry-count cap raised to 1,048,576* — To read large (ZIP64) archives, the default `bombPolicy.maxEntries` rises from 65535 to 2^20. An operator who set `maxEntries` explicitly is unaffected; the cap can still be lowered. **Fixed:** *`b.middleware.cspReport` returned 413 to every POST; `b.middleware.scimServer` broke on streamed bodies* — Both read the request body by calling `b.safeBuffer.boundedChunkCollector(req, …)` — but that primitive takes a single options object and returns a push-collector, it does not consume a stream. The call passed the request as the options argument (so `maxBytes` was undefined and it threw), turning every CSP-report POST into a 413 and failing every streamed SCIM request. Both now read the body through the new `b.safeBuffer.collectStream`. A valid CSP report now reaches the parse/audit/`onReport` path and returns 204. · *Agent orchestrator graceful-drain phase never registered* — `b.middleware.agentOrchestrator` registered its drain phase against a method the shutdown handle does not expose, so the phase silently never ran — connections were not drained on a graceful shutdown. It now registers through the real `addPhase` so the documented drain actually fires. · *OpenAPI / AsyncAPI doc endpoints ignored `accessControl: { allowOrigin }`* — The documented single-origin CORS form was read by neither serve middleware (only `accessControl: "public"` was handled), so an operator passing `{ allowOrigin: "https://docs.example.com" }` got no `Access-Control-Allow-Origin` header. The object form now emits a validated origin (passed through `b.safeUrl`, rejecting CR/LF injection, userinfo, and non-http(s) schemes) with `Vary: Origin`. · *EU AI Act Article 50 HTML banner skipped Buffer response bodies* — In HTML mode the disclosure banner was injected only when the final response chunk was a string; a `res.end(Buffer.from(html))` body (the common path through templating/render) silently received no banner. Buffer bodies are now decoded under the response charset, injected, and re-encoded (with a one-time warning and untouched bytes for charsets without a transcoder). · *Deny-path 429 (and any refusal) emitted `type: about:blank`* — The shared deny-path writer documented deriving the RFC 9457 problem-type URI from the refusal's problem code, but only ever read an explicit problem type — so a rate-limit 429 (which supplies a code, not a type) reported `about:blank`. The type is now derived from the problem code (`<base>/<code>`) when no explicit type is given, so a 429 reads `…/rate-limit-exceeded`. · *A deny-path `onDeny` hook that commits headers is treated as terminal* — The deny-path writer's terminal check looked only at `res.writableEnded`; a response-wrapping consumer whose `onDeny` sent headers without ending the response fell through into a second `writeHead` and hit "headers already sent". The writer now also treats `res.headersSent` as terminal, so wrapping responders compose cleanly. · *`b.mail.send.deliver` DANE TLSA lookup ignored the configured port* — The DANE TLSA query name (`_<port>._tcp.<host>`) was hardcoded to port 25; a delivery configured for a 587/465 relay still queried port 25. The lookup now uses the configured port. **Security:** *Closed a request-smuggling socket-reuse window on body-parse rejections* — Pairing every body-parse 4xx with `Connection: close` stops an upstream proxy from reusing a connection whose request body the parser abandoned mid-stream — a request/response desync vector that previously applied only to the chunked-decode rejections. · *Opt-in TLS-required posture for regulated external databases* — Set `requireTls: true` on an external-database backend carrying cardholder data or ePHI so a non-TLS (or fallback-permitting `sslmode`) connection is refused at boot rather than silently transmitting in the clear (PCI-DSS v4.0 Req 4 / HIPAA §164.312(e)). **Detectors:** *Regression guards for every fixed bug class* — The internal pattern gate gains detectors so each fixed mistake cannot return: a bounded-collector call used as a stream consumer, a deny-path writer that does not guard `headersSent`, an `appShutdown` phase registered through a non-existent method, a body-parse error writer missing `Connection: close`, a raw `_blamejs_jobs` table reference bypassing the configured-table quoting, and a breach clock that re-rolls its own timer instead of composing the incident-report clock. **Migration:** *No action required; new behavior is opt-in* — Every addition is additive or opt-in: `requireTls`, schema-drift `onDrift`, the response-shaping hooks, the new entry-point opts, and the breach clock all default to prior behavior when unset. Two defaults shift in a backward-compatible direction: body-parse 4xx now send `Connection: close`, and the archive reader's default entry-count ceiling rises to 2^20 (lower it via `bombPolicy.maxEntries` if you relied on the old cap). `b.db.reconcile` now returns a drift report object instead of undefined; the framework's own call ignores the return, so existing callers are unaffected.
+
 - v0.14.17 (2026-05-31) — **In-session API-encrypt errors stay confidential, and the encrypted client can read them.** When b.middleware.apiEncrypt is active, a normal response is sealed in the { _ct } envelope, but a terminal error that bypassed res.json (an error page, a validation refusal, an RFC 9457 problem+json document, a deny-middleware body) shipped in plaintext on the otherwise-encrypted channel, and the b.httpClient.encrypted client threw on the response shape because it tried to decrypt every reply. This release makes errors symmetric: those four sinks now seal their body in the same envelope a success uses whenever a session is active (via a new req.apiEncryptEncode the middleware installs after a successful decrypt), and the client gains a responseMode: "passthrough" that reads a non-2xx — decrypting an in-session error and returning a plaintext one verbatim — instead of throwing. Errors raised before a session exists (a Bearer 401, a handshake rejection, a replay refusal) deliberately stay plaintext and human-readable. Two adjacent streaming fixes ride along: a streamed (responseMode "stream") non-2xx now keeps a bounded prefix of the error body on the thrown error instead of draining it, and an SSE channel closed by a transport fault audits as a failure with a reason rather than looking like a clean operator close. **Added:** *`b.httpClient.encrypted` gains `responseMode: "passthrough"`* — The encrypted client defaults to `responseMode: "reject"` (a non-2xx rejects, exactly as before). Set `responseMode: "passthrough"` at create time, or per request, to resolve a non-2xx instead: the result is `{ statusCode, headers, body, ok }`, where `body` is the decrypted object when the reply carries an encrypted `_ct` envelope (an in-session error) and the parsed plaintext otherwise (a pre-session error such as a Bearer 401 or a proxy 502). The additive `ok` boolean (status 200–299) is present on every result. This lets a client read an error's status and detail instead of failing on the response shape. · *`req.apiEncryptEncode` — the in-session error encoder* — `b.middleware.apiEncrypt` installs `req.apiEncryptEncode(obj)` after it successfully decrypts a request body. It returns the same `{ _ct }` (plus `_sid` / `_ctr` in per-session mode) envelope a normal response uses, so a terminal handler that writes its body directly (bypassing the wrapped `res.json`) can keep an error confidential on the encrypted channel. It is present only after a valid decrypt, so every pre-session path has no encoder and its errors stay plaintext. **Changed:** *In-session terminal errors are sealed in the encrypted envelope* — The error page (JSON branch), the router's schema-validation refusal, `b.problemDetails.respond` (now accepting an optional `req`), and the access-deny middleware now seal their error body via `req.apiEncryptEncode` when a session is active — so an in-session error no longer ships as plaintext while the surrounding traffic is encrypted. A sealed problem+json is labelled `application/json` (the envelope), not `application/problem+json`. With no active session (or if encoding fails) the body stays plaintext and readable, unchanged. · *Streamed non-2xx responses preserve a bounded error-body prefix* — `b.httpClient.request({ responseMode: "stream" })` (and `b.httpClient.downloadStream`, which composes it) previously drained and discarded the body of a `>= 400` response. The rejection is unchanged, but the thrown error now carries a bounded (16 KiB) prefix of the body on `err.body`, so a caller can read the problem+json / error detail. The prefix is collected through `b.safeBuffer.boundedChunkCollector`, so a hostile oversized error body can't accumulate unbounded. · *SSE transport-fault close audits as a failure* — An SSE channel closed by a transport fault (a stream `error`, a failed heartbeat write) now emits its `sse.channel_closed` audit event with `outcome: "failure"` and a `reason`, instead of the `"success"` outcome an intentional `channel.close()` records — so an operator's evidence stream can tell a dropped connection from a clean shutdown. **Security:** *Error bodies no longer leak in plaintext on an encrypted channel* — Before this release, a request that established an apiEncrypt session but then failed (validation error, access denial, server error rendered through the error page or problem-details) returned its error body in plaintext, even though every successful response on the same channel was encrypted — exposing error detail (paths, field names, refusal reasons) to a network observer. In-session errors are now encrypted symmetrically with successes; pre-session errors, which a client must be able to read to recover, remain plaintext by design. **Migration:** *Opt into reading non-2xx encrypted errors* — No change is required for existing callers — `b.httpClient.encrypted` still defaults to `responseMode: "reject"` (throw on non-2xx). To read an error's status and decrypted detail, create the client with `responseMode: "passthrough"` (or pass it per request) and branch on the returned `ok` / `statusCode`. The new `ok` field is additive and does not affect existing `{ statusCode, headers, body }` consumers.
 
 - v0.14.16 (2026-05-31) — **Connection entry-point ports are validated at config time.** Six connection entry points previously read opts.port with a bare `|| <default>` fallback, silently coercing a string, negative, NaN, or out-of-range port instead of catching the operator's typo. A new b.validateOpts.optionalPort enforces the RFC 6335 §6 wire-valid range and is wired into b.mail.smtpTransport, b.ntpCheck.querySingle, b.networkDns.useDnsOverTls, b.networkNts (KE handshake / query / facade), b.redisClient.create, and createApp().listen — each now throws at construction with a clear message naming the bad value. The app.listen / createApp bind site opts into allowZero so port 0 (the legitimate ephemeral-bind sentinel) still works; the five outbound-connect sites require [1,65535]. **Added:** *`b.validateOpts.optionalPort`* — A config-time port validator: `optionalPort(value, label, errorClass, code, opts?)` returns an omitted (`undefined` / `null`) port unchanged, and otherwise requires an integer in the RFC 6335 §6 wire-valid range [1,65535] — rejecting a string, negative, NaN, Infinity, fractional, or out-of-range value. Pass `{ allowZero: true }` for a listen-bind site where port 0 is the OS ephemeral-bind sentinel. The thrown message reports the offending shape (so `Infinity` / `"443"` stay visible), and routes a caller-supplied typed framework error (or a plain Error when none is given), matching the existing `optionalPositiveFinite` family. **Changed:** *Connection entry points reject a malformed port at construction* — `b.mail.smtpTransport`, `b.ntpCheck.querySingle`, `b.networkDns.useDnsOverTls`, `b.networkNts.performKeHandshake` / `query` / `querySingle`, `b.redisClient.create`, and `createApp().listen` (plus the `createApp` constructor's default port) now validate `opts.port` and throw synchronously on a non-integer / out-of-range value rather than coercing it through `||` to a default. This is a behavior change for a caller that was passing a non-canonical port (e.g. the string `"587"` or a NaN) and relying on the silent fallback — pass an integer in [1,65535] instead (or `0` for an ephemeral `createApp().listen` bind). `b.ntpCheck` gains a typed `NtpCheckError` for this (it had no error class before). **Detectors:** *Connection entry points must compose the port validator* — A new check flags a lib connection entry point that reads `opts.port` / `opts.kePort` / `opts.ntpPort` with a `|| <default>` fallback without composing `b.validateOpts.optionalPort` (or the equivalent `numericBounds.isPositiveFiniteInt` + 65535 cap), so an unvalidated port read can't slip back in. **Migration:** *Pass an integer port to connection primitives* — If you were passing a non-integer or out-of-range `opts.port` to a mail / NTP / NTS / DNS-over-TLS / Redis transport or to `createApp().listen` and relying on the silent `|| default` fallback, that now throws at construction. Pass an integer in [1,65535]; for an ephemeral `createApp().listen` bind, pass `0` (still accepted).

package/README.md

@@ -64,9 +64,9 @@ The framework bundles the surface a typical Node app reaches for. Every primitiv
 - **Chainable query builder** — 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 }`; a column-membership gate (`db.init({ columnGate })`, default reject) fails a query closed when it names a column the table never declared, and `whereRaw` refuses an embedded string literal so values bind through placeholders
 - **Mongo-style document-store facade** — `b.db.collection(name, opts?)` with `$set` / `$inc` / `$unset` / `$eq` / `$ne` / `$gt` / `$gte` / `$lt` / `$lte` / `$in` / `$like`; schemaless-document opts via `overflow: "<col>"` (folds unknown fields into a JSON-text column; rewrites `WHERE` on virtual fields to `JSON_EXTRACT`), `jsonColumns: [...]` (auto-stringify on write + parse via `b.safeJson` on read), `sealedFields: { email: "emailHash" }` (co-locates a `b.cryptoField` sealed-column / derived-hash declaration so plaintext lookups auto-rewrite to hash-column lookups)
 - **DB lifecycle** — in-memory encrypted snapshot via `b.db.snapshot()`; standalone encrypted-DB-file lifecycle (`b.db.fileLifecycle({ dataDir, vault })` — decrypt-to-tmpfs, periodic re-encrypt flush, graceful shutdown — same envelope as `b.db`, no schema/audit-chain coupling); `db.init` opt-outs `frameworkTables: false` / `auditSigning: false` and path overrides `encryptedDbPath` / `encryptedDbName` / `dbKeyPath`
-- **External RDBMS** — bring-your-own Postgres / MySQL 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`)
+- **External RDBMS** — bring-your-own Postgres / MySQL 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`); an opt-in `requireTls` transport posture refuses a non-TLS backend at boot, and query / transaction / read traces carry OpenTelemetry `db.*` attributes
 - **Object store** — S3 / R2 / B2 / GCS / Azure with multipart upload + SSE + bucket-ops (create / delete / list / lifecycle / CORS); S3 Object Lock + per-object retention + legal hold for write-once-read-many compliance workloads (`b.storage`, `b.objectStore`)
-- **Queues + cache** — durable queue with priority + cron + flows on local SQLite, shared Redis, OR AWS SQS via SigV4 + AWSJsonProtocol_1.0 (`b.queue`, `b.jobs`); cluster-shared cache (`b.cache`)
+- **Queues + cache** — durable queue with priority + cron + flows on local SQLite, shared Redis, OR AWS SQS via SigV4 + AWSJsonProtocol_1.0 (`b.queue`, `b.jobs`) — the local backend can target an operator-supplied database / table / schema; cluster-shared cache (`b.cache`)
 ### Identity & access
 
 - **Passwords** — Argon2id + policy primitive (`b.auth.password`); NIST 800-63B / PCI-DSS 4.0 / HIPAA-AAL2 profiles; HaveIBeenPwned k-anonymity breach check; length / context / dictionary / complexity rules; rotation + history
@@ -119,7 +119,7 @@ The framework bundles the surface a typical Node app reaches for. Every primitiv
 - **mTLS CA** — pure-JS, issues clientAuth / serverAuth / dual-EKU certs with SAN; auto-detects highest-PQC signature alg (today ECDSA-P384-SHA384; self-upgrades to SLH-DSA / ML-DSA when X.509 ecosystem catches up); PQC TLS gates inbound + outbound (`b.mtlsCa`, `b.pqcGate`, `b.pqcAgent`)
 ### HTTP
 
-- **Router + API specs** — schema-validated routes; OpenAPI publication (`b.openapi`) + AsyncAPI publication for event/streaming (`b.asyncapi`)
+- **Router + API specs** — schema-validated routes; OpenAPI 3.1 / 3.2 publication (`b.openapi` — webhooks + `jsonSchemaDialect`) + AsyncAPI publication for event/streaming (`b.asyncapi`)
 - **Middleware stack (`createApp`)** — security layers wired ON by default (Core Rule §3); each is configurable via `middleware.<name>` (operator cookie / field names flow straight through — nothing static is baked in) or opt-out with `false` (disabling a default is audited via `app.middleware.disabled`). Ordered so each layer has what it needs (cookies + CSP nonce + fetch-metadata, then body parser, then CSRF last):
   - Request-ID tagging and bot-guard
   - Security headers with `Permissions-Policy` defaults denying storage-access / browsing-topics / private-aggregation / controlled-frame

package/lib/agent-orchestrator.js

@@ -146,7 +146,7 @@ var _saltedFnvBasisCache = null;
  *   permissions:  b.permissions instance,       // optional; orchestrator skips RBAC if absent
  *   backend:      { get, set, delete, list },   // optional; in-memory default
  *   cluster:      b.cluster module,             // optional; defaults to b.cluster
- *   appShutdown:  b.appShutdown.create()        // optional; orchestrator registers drain phase if supplied
+ *   appShutdown:  b.appShutdown.create()        // optional; orchestrator adds an "agent.orchestrator.drain" phase via addPhase() if supplied
  *
  * @example
  *   var orch = b.agent.orchestrator.create({});
@@ -201,9 +201,15 @@ function create(opts) {
   };
 
   // Wire the drain phase into b.appShutdown if the operator supplied one.
-  if (opts.appShutdown && typeof opts.appShutdown.registerPhase === "function") {
-    opts.appShutdown.registerPhase("agent.orchestrator.drain", function () {
-      return _drain(ctx, { timeoutMs: DEFAULT_DRAIN_TIMEOUT_MS });
+  // The orchestrator handle exposes addPhase({ name, run, timeoutMs? })
+  // (b.appShutdown.create), so the drain registers as a named phase that
+  // the orchestrator runs in array order during graceful shutdown.
+  if (opts.appShutdown && typeof opts.appShutdown.addPhase === "function") {
+    opts.appShutdown.addPhase({
+      name: "agent.orchestrator.drain",
+      run:  function () {
+        return _drain(ctx, { timeoutMs: DEFAULT_DRAIN_TIMEOUT_MS });
+      },
     });
   }
 

package/lib/ai-prompt.js

@@ -65,7 +65,7 @@ var ROLE_CONTROL_TOKENS = [
 
 // Escape a string for safe inclusion in a RegExp character/literal body.
 function _reEscape(s) {
-  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  return codepointClass.escapeRegExp(s);
 }
 
 // Build the per-render boundary tokens for a role. The nonce binds the

package/lib/app-shutdown.js

@@ -43,6 +43,7 @@
 
 var safeAsync = require("./safe-async");
 var numericBounds = require("./numeric-bounds");
+var validateOpts = require("./validate-opts");
 var tracing = null;
 try { tracing = require("./tracing"); } catch (_e) { /* tracing optional */ }
 var { defineClass } = require("./framework-error");
@@ -79,6 +80,7 @@ var FORCE_EXIT_MARGIN_MS = C.TIME.seconds(5);
  *   phases:                array,     // [{ name, run: async fn, timeoutMs? }]
  *   installSignalHandlers: boolean,   // wire SIGTERM/SIGINT (default false)
  *   signals:               array,     // signal names (default ["SIGTERM","SIGINT"])
+ *   exitAfterPhases:       boolean,   // when true, a non-signal shutdown() also process.exit()s once phases complete (default false — only the signal path exits)
  *   onUncaught:            function,  // hook for uncaughtException / unhandledRejection
  *   installUncaught:       boolean,   // wire uncaughtException handler unconditionally
  *
@@ -102,6 +104,17 @@ function create(opts) {
   numericBounds.requirePositiveFiniteIntIfPresent(opts.forceExitMarginMs,
     "app-shutdown.create: opts.forceExitMarginMs", AppShutdownError, "app-shutdown/bad-force-exit-margin-ms");
   var forceExitMarginMs = opts.forceExitMarginMs !== undefined ? opts.forceExitMarginMs : FORCE_EXIT_MARGIN_MS;
+  // By default the process exits only via the signal-handler path (a
+  // received SIGTERM/SIGINT sets process.exitCode and lets the event loop
+  // drain). A manual orchestrator.shutdown() — invoked from an admin
+  // endpoint, a test harness, or a non-signal lifecycle hook — resolves
+  // its Promise but does NOT terminate the process, so exit-coupled
+  // teardown (the registered process-exit handlers that run the final DB
+  // re-encrypt) never fires. Set exitAfterPhases:true so a non-signal
+  // shutdown() also exits once every phase has completed.
+  validateOpts.optionalBoolean(opts.exitAfterPhases,
+    "app-shutdown.create: opts.exitAfterPhases", AppShutdownError, "app-shutdown/bad-exit-after-phases");
+  var exitAfterPhases = opts.exitAfterPhases === true;
   var phases = Array.isArray(opts.phases) ? opts.phases.slice() : [];
   var installSignalHandlers = !!opts.installSignalHandlers;
   for (var i = 0; i < phases.length; i++) {
@@ -224,6 +237,21 @@ function create(opts) {
       log("shutdown complete in " + totalMs + "ms (" +
           phaseResults.filter(function (p) { return p.ok; }).length + "/" +
           phaseResults.length + " phases ok)");
+      if (exitAfterPhases) {
+        // Caller opted to couple a non-signal shutdown() to process exit.
+        // Scheduled on the next tick so the awaiting caller's resolution
+        // handler runs first; process.exit() then runs the registered
+        // exit handlers (the final DB re-encrypt). Preserve an exit code
+        // an operator hook may already have set; otherwise derive from
+        // phase success.
+        var exitCode = (process.exitCode !== undefined && process.exitCode !== 0)
+          ? process.exitCode : (allOk ? 0 : 1);
+        setImmediate(function () {
+          // allow:process-exit — operator opted into exitAfterPhases,
+          // delegating process lifecycle to the orchestrator
+          process.exit(exitCode);
+        });
+      }
       return { ok: allOk, phases: phaseResults, totalMs: totalMs, draining: true };
     })();
     return shutdownPromise;

package/lib/archive-read.js

@@ -64,7 +64,26 @@ var SIG_EOCD                = 0x06054b50;       // APPNOTE §4.3.16 EOCD magic d
 var SIG_EOCD64              = 0x06064b50;       // APPNOTE §4.3.14 ZIP64 EOCD magic dword (wire-format-fixed)
 var SIG_EOCD64_LOCATOR      = 0x07064b50;       // APPNOTE §4.3.15 ZIP64 EOCD locator magic dword (wire-format-fixed)
 var SIG_DATA_DESCRIPTOR     = 0x08074b50;       // APPNOTE §4.3.9 data-descriptor magic dword (wire-format-fixed)
-void SIG_EOCD64; void SIG_EOCD64_LOCATOR;
+
+// ZIP64 sentinels — a classic record field set to its all-ones value
+// means "the real value lives in the ZIP64 record / extra field"
+// (APPNOTE §4.4 + §4.5.3). 16-bit fields use 0xFFFF, 32-bit fields use
+// 0xFFFFFFFF.
+var ZIP64_U16_SENTINEL      = 0xffff;           // APPNOTE §4.4.21/§4.4.22 16-bit overflow marker
+var ZIP64_U32_SENTINEL      = 0xffffffff;       // APPNOTE §4.4.8/§4.4.16/§4.4.24 32-bit overflow marker
+
+// ZIP64 EOCD locator (§4.3.15) is fixed at 20 bytes:
+//   sig(4) diskWithEocd64(4) eocd64Offset(8) totalDisks(4)
+var EOCD64_LOCATOR_BYTES    = C.BYTES.bytes(20);
+// ZIP64 EOCD record (§4.3.14) fixed prefix is 56 bytes through the
+// cdOffset field; a variable-length "extensible data sector" may follow,
+// sized by the 8-byte "size of ZIP64 EOCD record" field.
+var EOCD64_FIXED_BYTES      = C.BYTES.bytes(56);
+// ZIP64 extended-information extra field (§4.5.3) header is 4 bytes
+// (id(2) + dataSize(2)); each present value is an 8-byte little-endian
+// dword except diskStart which is a 4-byte dword.
+var ZIP64_EXTRA_HEADER_ID   = 0x0001;           // APPNOTE §4.5.3 ZIP64 extra-field tag
+var EXTRA_FIELD_HEADER_BYTES= C.BYTES.bytes(4);
 
 var METHOD_STORE_ID         = 0;
 var METHOD_DEFLATE_ID       = 8;
@@ -94,7 +113,7 @@ var MSDOS_EPOCH_YEAR        = 1980;
 // ---- Default zip-bomb / entry caps ---------------------------------------
 
 var DEFAULT_BOMB_POLICY = Object.freeze({
-  maxEntries:                65535,                                   // APPNOTE §4.4.21 16-bit entry-count field's max (ZIP64 deferred)
+  maxEntries:                1048576,                                 // 2^20 entry-count cap (ZIP64 lifts the classic 16-bit 65535 limit; operators raise via bombPolicy)
   maxEntryDecompressedBytes: C.BYTES.mib(128),                  // per-entry cap
   maxTotalDecompressedBytes: C.BYTES.gib(4),                    // archive-wide cap
   maxExpansionRatio:         100,                                     // compressed → decompressed ratio cap
@@ -120,6 +139,22 @@ function _msdosToDate(dosDate, dosTime) {
   return new Date(year, month, day, hour, minute, second);
 }
 
+// Read an 8-byte little-endian ZIP64 dword as a JS number. ZIP64 sizes
+// and offsets are 64-bit (APPNOTE §4.3.14/§4.5.3); JS numbers address up
+// to 2^53-1 exactly, which is far above any value the reader can act on
+// (a single decompressed entry is bomb-capped well under 2^53 bytes).
+// Anything above MAX_SAFE_INTEGER is refused as unaddressable rather
+// than silently truncated.
+function _readZip64U64(buf, off, fieldLabel) {
+  var big = buf.readBigUInt64LE(off);
+  if (big > BigInt(Number.MAX_SAFE_INTEGER)) {
+    throw new ArchiveReadError("archive-read/zip64-value-too-large",
+      "ZIP64 " + fieldLabel + "=" + big.toString() +
+      " exceeds the addressable Number.MAX_SAFE_INTEGER ceiling");
+  }
+  return Number(big);
+}
+
 function _isUnixSymlinkAttrs(externalAttrs) {
   // S_IFLNK = 0o120000 (octal). External file attributes' high 16 bits
   // carry the unix mode when "version made by" host == 3 (UNIX).
@@ -189,7 +224,7 @@ async function _locateEocd(adapter) {
       // past EOF and we keep scanning.
       var commentLen = tail.readUInt16LE(i + 20);
       if (i + EOCD_MIN_BYTES + commentLen === tail.length) {
-        return {
+        var eocd = {
           eocdOffset:           scanOffset + i,
           diskNumber:           tail.readUInt16LE(i + 4),
           cdDiskNumber:         tail.readUInt16LE(i + 6),
@@ -198,7 +233,18 @@ async function _locateEocd(adapter) {
           cdSize:               tail.readUInt32LE(i + 12),           // APPNOTE §4.3.16 EOCD field offset
           cdOffset:             tail.readUInt32LE(i + 16),           // APPNOTE §4.3.16 EOCD field offset
           commentLength:        commentLen,
+          isZip64:              false,
         };
+        // When any classic field carries the ZIP64 sentinel, the true
+        // values live in the ZIP64 EOCD record located via the ZIP64
+        // locator that immediately precedes this classic EOCD
+        // (APPNOTE §4.3.15). Resolve them in place.
+        if (eocd.totalEntries === ZIP64_U16_SENTINEL ||
+            eocd.cdSize === ZIP64_U32_SENTINEL ||
+            eocd.cdOffset === ZIP64_U32_SENTINEL) {
+          await _resolveZip64Eocd(adapter, eocd, size);
+        }
+        return eocd;
       }
     }
   }
@@ -206,6 +252,127 @@ async function _locateEocd(adapter) {
     "End-of-central-directory record not found in trailing " + scanLen + " bytes");
 }
 
+// ---- ZIP64 EOCD resolution ------------------------------------------------
+// Reads the ZIP64 EOCD locator (§4.3.15) that precedes the classic EOCD,
+// follows it to the ZIP64 EOCD record (§4.3.14), and overlays the 64-bit
+// totalEntries / centralDirSize / centralDirOffset onto the eocd object.
+// Mutates `eocd` in place (sets isZip64 + the 64-bit fields).
+async function _resolveZip64Eocd(adapter, eocd, archiveSize) {
+  var locatorOffset = eocd.eocdOffset - EOCD64_LOCATOR_BYTES;
+  if (locatorOffset < 0) {
+    throw new ArchiveReadError("archive-read/zip64-locator-missing",
+      "classic EOCD carries a ZIP64 sentinel but no room for the ZIP64 locator before it");
+  }
+  var locator = await adapter.range(locatorOffset, EOCD64_LOCATOR_BYTES);
+  if (locator.readUInt32LE(0) !== SIG_EOCD64_LOCATOR) {
+    throw new ArchiveReadError("archive-read/zip64-locator-missing",
+      "expected ZIP64 EOCD locator signature before classic EOCD, got 0x" +
+      locator.readUInt32LE(0).toString(16));                                 // radix=16 for hex parse, not byte count
+  }
+  // diskWithEocd64 (offset 4) + totalDisks (offset 16) — single-disk only.
+  if (locator.readUInt32LE(4) !== 0 || locator.readUInt32LE(16) > 1) {
+    throw new ArchiveReadError("archive-read/multi-disk",
+      "multi-disk ZIP64 archives are not supported (totalDisks=" +
+      locator.readUInt32LE(16) + ")");
+  }
+  var eocd64Offset = _readZip64U64(locator, 8, "EOCD64 record offset");      // §4.3.15 locator field
+  if (eocd64Offset + EOCD64_FIXED_BYTES > archiveSize) {
+    throw new ArchiveReadError("archive-read/zip64-eocd-out-of-range",
+      "ZIP64 EOCD record offset=" + eocd64Offset + " overflows archive size=" + archiveSize);
+  }
+  var rec = await adapter.range(eocd64Offset, EOCD64_FIXED_BYTES);
+  if (rec.readUInt32LE(0) !== SIG_EOCD64) {
+    throw new ArchiveReadError("archive-read/zip64-eocd-bad-signature",
+      "ZIP64 EOCD record has bad signature 0x" + rec.readUInt32LE(0).toString(16));   // radix=16 for hex parse, not byte count
+  }
+  // diskNumber (offset 16) + cdDiskNumber (offset 20) — single-disk only.
+  eocd.diskNumber   = rec.readUInt32LE(16);                                   // §4.3.14 ZIP64 EOCD field
+  eocd.cdDiskNumber = rec.readUInt32LE(20);                                   // §4.3.14 ZIP64 EOCD field
+  eocd.totalEntries = _readZip64U64(rec, 32, "totalEntries");                 // §4.3.14 ZIP64 EOCD field
+  eocd.cdSize       = _readZip64U64(rec, 40, "centralDirSize");               // §4.3.14 ZIP64 EOCD field
+  eocd.cdOffset     = _readZip64U64(rec, 48, "centralDirOffset");             // §4.3.14 ZIP64 EOCD field
+  eocd.isZip64      = true;
+}
+
+// ---- ZIP64 extended-information extra field (§4.5.3) ----------------------
+// The ZIP64 extra field (header id 0x0001) supplies the true 64-bit
+// values for ONLY the fields that carried the 0xFFFFFFFF / 0xFFFF
+// sentinel in the classic CFH, and they appear in a FIXED ORDER:
+//   uncompressedSize, compressedSize, localHeaderOffset, diskStart.
+// The data-block length tells us how many of those are present; a
+// field is present iff its classic value was the sentinel AND the
+// data block is long enough to carry it. Returns the resolved values,
+// leaving any non-sentinel field at its classic value.
+function _applyZip64Extra(classic, extraFields) {
+  var resolved = {
+    uncompressedSize: classic.uncompressedSize,
+    compressedSize:   classic.compressedSize,
+    lfhOffset:        classic.lfhOffset,
+  };
+  var needUncompressed = classic.uncompressedSize === ZIP64_U32_SENTINEL;
+  var needCompressed   = classic.compressedSize   === ZIP64_U32_SENTINEL;
+  var needLfhOffset    = classic.lfhOffset        === ZIP64_U32_SENTINEL;
+  var needDiskStart    = classic.diskStart        === ZIP64_U16_SENTINEL;
+  if (!needUncompressed && !needCompressed && !needLfhOffset && !needDiskStart) {
+    return resolved;  // no ZIP64 fields needed — classic values stand
+  }
+  // Walk the extra-field chain (id(2) + size(2) + data) looking for 0x0001.
+  var p = 0;
+  while (p + EXTRA_FIELD_HEADER_BYTES <= extraFields.length) {
+    var id   = extraFields.readUInt16LE(p);                                   // §4.5.1 extra-field header id
+    var dataSize = extraFields.readUInt16LE(p + 2);                           // §4.5.1 extra-field data size
+    var dataStart = p + EXTRA_FIELD_HEADER_BYTES;
+    if (dataStart + dataSize > extraFields.length) break;  // truncated extra block — stop
+    if (id === ZIP64_EXTRA_HEADER_ID) {
+      var q = dataStart;
+      var end = dataStart + dataSize;
+      // Order-dependent per §4.5.3 — only the fields whose classic value
+      // was the sentinel are present, in this exact sequence.
+      if (needUncompressed) {
+        if (q + 8 > end) {
+          throw new ArchiveReadError("archive-read/zip64-extra-truncated",
+            "ZIP64 extra field too short for uncompressedSize");
+        }
+        resolved.uncompressedSize = _readZip64U64(extraFields, q, "extra uncompressedSize");
+        q += 8;
+      }
+      if (needCompressed) {
+        if (q + 8 > end) {
+          throw new ArchiveReadError("archive-read/zip64-extra-truncated",
+            "ZIP64 extra field too short for compressedSize");
+        }
+        resolved.compressedSize = _readZip64U64(extraFields, q, "extra compressedSize");
+        q += 8;
+      }
+      if (needLfhOffset) {
+        if (q + 8 > end) {
+          throw new ArchiveReadError("archive-read/zip64-extra-truncated",
+            "ZIP64 extra field too short for localHeaderOffset");
+        }
+        resolved.lfhOffset = _readZip64U64(extraFields, q, "extra localHeaderOffset");
+        q += 8;
+      }
+      if (needDiskStart) {
+        if (q + 4 > end) {
+          throw new ArchiveReadError("archive-read/zip64-extra-truncated",
+            "ZIP64 extra field too short for diskStart");
+        }
+        // diskStart must be 0 (single-disk). Read but enforce single-disk.
+        if (extraFields.readUInt32LE(q) !== 0) {
+          throw new ArchiveReadError("archive-read/multi-disk",
+            "ZIP64 entry references a non-zero disk start (multi-disk unsupported)");
+        }
+        q += 4;
+      }
+      return resolved;
+    }
+    p = dataStart + dataSize;
+  }
+  // A sentinel was present but no 0x0001 block resolved it — malformed.
+  throw new ArchiveReadError("archive-read/zip64-extra-missing",
+    "central directory entry carries a ZIP64 sentinel size but no ZIP64 extended-information extra field (id 0x0001)");
+}
+
 // ---- Random-access central-directory walk ---------------------------------
 
 async function _readCentralDirectory(adapter, eocd) {
@@ -213,12 +380,15 @@ async function _readCentralDirectory(adapter, eocd) {
     throw new ArchiveReadError("archive-read/multi-disk",
       "multi-disk archives are not supported (diskNumber=" + eocd.diskNumber + ")");
   }
-  if (eocd.totalEntries === 0xffff || eocd.cdSize === 0xffffffff || eocd.cdOffset === 0xffffffff) {
-    // ZIP64 sentinel — unsupported. Archives at >4 GiB / >65535 entries
-    // use tar instead (the escape hatch); ZIP64 read support is deferred
-    // until an operator surfaces a need.
-    throw new ArchiveReadError("archive-read/zip64-unsupported",
-      "ZIP64 archives are unsupported (operators at >4 GiB / >65535 entries should switch to tar)");
+  // ZIP64 sentinels in the classic EOCD are resolved by `_locateEocd`
+  // (via the ZIP64 EOCD locator + record). If any sentinel still stands
+  // here the classic record claimed ZIP64 but the ZIP64 trailer was
+  // absent — refuse rather than reading a sentinel as a literal count.
+  if (eocd.totalEntries === ZIP64_U16_SENTINEL ||
+      eocd.cdSize === ZIP64_U32_SENTINEL ||
+      eocd.cdOffset === ZIP64_U32_SENTINEL) {
+    throw new ArchiveReadError("archive-read/zip64-eocd-unresolved",
+      "classic EOCD carries a ZIP64 sentinel but the ZIP64 EOCD record did not resolve it");
   }
   if (eocd.cdSize === 0 || eocd.totalEntries === 0) {
     return [];
@@ -246,6 +416,7 @@ async function _readCentralDirectory(adapter, eocd) {
     var nameLen          = cdBytes.readUInt16LE(pos + 28);                 // APPNOTE §4.3.12 CFH field offset
     var extraLen         = cdBytes.readUInt16LE(pos + 30);                 // APPNOTE §4.3.12 CFH field offset
     var commentLen       = cdBytes.readUInt16LE(pos + 32);                 // APPNOTE §4.3.12 CFH field offset
+    var diskStart        = cdBytes.readUInt16LE(pos + 34);                 // APPNOTE §4.3.12 CFH field offset (disk number start)
     var externalAttrs    = cdBytes.readUInt32LE(pos + 38);                 // APPNOTE §4.3.12 CFH field offset
     var lfhOffset        = cdBytes.readUInt32LE(pos + 42);                 // APPNOTE §4.3.12 CFH field offset
     var nameStart        = pos + CFH_FIXED_BYTES;
@@ -255,27 +426,31 @@ async function _readCentralDirectory(adapter, eocd) {
       throw new ArchiveReadError("archive-read/cd-truncated",
         "central directory entry " + n + " variable-length fields overflow CD");
     }
-    if (compressedSize === 0xffffffff || uncompressedSize === 0xffffffff || lfhOffset === 0xffffffff) {
-      throw new ArchiveReadError("archive-read/zip64-unsupported",
-        "central directory entry " + n + " carries ZIP64 sentinel sizes (unsupported — use tar for >4 GiB / >65535 entries)");
-    }
     // ZIP names are CP437 or UTF-8 (per FLAG_UTF8_NAME bit). Decode
     // as UTF-8 unconditionally — a concern if operators in
     // the wild rely on CP437; v0.12.7 ships UTF-8 only and operators
     // with legacy CP437-only producers reach for an external decoder.
     var name = cdBytes.slice(nameStart, nameStart + nameLen).toString("utf8");
     var extraFields = cdBytes.slice(extraStart, extraStart + extraLen);
+    // Resolve ZIP64 sentinel sizes/offsets from the §4.5.3 extra field
+    // (id 0x0001) — order-dependent, present only for sentinel values.
+    var resolved = _applyZip64Extra({
+      uncompressedSize: uncompressedSize,
+      compressedSize:   compressedSize,
+      lfhOffset:        lfhOffset,
+      diskStart:        diskStart,
+    }, extraFields);
     entries.push({
       name:             name,
       method:           method,
       generalFlags:     generalFlags,
       crc:              crc32,
-      compressedSize:   compressedSize,
-      uncompressedSize: uncompressedSize,
+      compressedSize:   resolved.compressedSize,
+      uncompressedSize: resolved.uncompressedSize,
       mtime:            _msdosToDate(dosDate, dosTime),
       externalAttrs:    externalAttrs,
       extraFields:      extraFields,
-      lfhOffset:        lfhOffset,
+      lfhOffset:        resolved.lfhOffset,
       isEncrypted:      (generalFlags & FLAG_ENCRYPTED) !== 0,
       hasDataDescriptor:(generalFlags & FLAG_DATA_DESCRIPTOR) !== 0,
       _entryType:       null,  // memoized on first access
@@ -306,6 +481,23 @@ async function _verifyLfhMatchesCd(adapter, entry) {
       "entry " + JSON.stringify(entry.name) + " method skew: LFH=" +
       lfhMethod + " CD=" + entry.method);
   }
+  // ZIP64: when the LFH's 32-bit csize/usize carry the sentinel, the
+  // true 64-bit values live in the LFH's ZIP64 extra field (§4.5.3).
+  // In the LFH variant both sizes are present (uncompressed then
+  // compressed) when either overflowed. Resolve before the skew check
+  // so the comparison runs against the CD's resolved 64-bit values.
+  if (!hasDataDescriptor &&
+      (lfhUsize === ZIP64_U32_SENTINEL || lfhCsize === ZIP64_U32_SENTINEL)) {
+    var lfhExtra = await adapter.range(entry.lfhOffset + LFH_FIXED_BYTES + lfhNameLen, lfhExtraLen);
+    var lfhResolved = _applyZip64Extra({
+      uncompressedSize: lfhUsize,
+      compressedSize:   lfhCsize,
+      lfhOffset:        0,             // LFH ZIP64 extra never carries an offset; never a sentinel here
+      diskStart:        0,             // ditto — no disk-start in the LFH extra
+    }, lfhExtra);
+    lfhUsize = lfhResolved.uncompressedSize;
+    lfhCsize = lfhResolved.compressedSize;
+  }
   // When the data-descriptor flag is set, the LFH's crc/csize/usize
   // are all zero per APPNOTE §4.4.4 bit 3 — skip the comparison.
   if (!hasDataDescriptor) {
@@ -462,6 +654,13 @@ function _emitAudit(opts, action, outcome, metadata) {
  * `extract(opts)` (full decompression with bomb caps + path-traversal +
  * entry-type policy).
  *
+ * ZIP64 (APPNOTE 6.3.10 §4.3.14 EOCD64 / §4.3.15 locator / §4.5.3
+ * extended-information extra field) is read transparently: archives
+ * whose entry count exceeds 65535 or whose sizes/offsets exceed 4 GiB
+ * carry the ZIP64 trailer, which is resolved into the same entry shape
+ * a classic archive yields. The classic-format default entry cap is
+ * lifted to 2^20; operators raise it through `bombPolicy.maxEntries`.
+ *
  * Defends:
  *   - Zip Slip / path traversal (CVE-2025-3445 / 11569 / 23084 / 27210
  *     / 11001 / 11002 / 26960 + 2024 jszip / mholt / Python tarfile)