gina 0.6.7 → 0.6.8

package/CHANGELOG.md

@@ -6,6 +6,28 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html),
 and is generated by [Changie](https://github.com/miniscruff/changie).
 
 
+## 0.6.8 - 2026-08-15
+### Added
+* Storage drivers can now read a byte range. `getRange(key, start, end, cb)` ships on every local strategy (`sharded`, `cas` and `stream`) and `capabilities.ranges` is true for all of them, where it was false in every prior release. `end` is INCLUSIVE, matching the HTTP `Range` header, so a header's byte offsets pass through unchanged; an `end` past the last byte is clamped rather than refused, and only a `start` at or beyond the object's size is unsatisfiable — that is the caller's `416`. Both size tiers answer (an inline object slices its stored bytes, a published one gets a positioned read), and under `cas` a released blob stays invisible to `getRange()` exactly as it already is to `get()`. The serving half ships alongside it: `self.serveFromStorage()` answers `206`/`416`/`304` with `Accept-Ranges`/`Content-Range` on both engines, gated on `capabilities.ranges`, so a controller only reaches for raw `getRange()` when it wants custom protocol handling.
+* The storage layer can now keep its metadata on Couchbase, which is what makes a driver root shareable: the embedded SQLite default is documented single-process-per-root, so two bundles — or two replicas of one — could not share a root until now. Point a driver's `store` at a `connectors.json` entry whose `connector` is `couchbase` (SDK major 3 or 4, installed in your own project — the framework still declares no dependency on it) and every metadata row, inline payloads included, lives on the cluster instead of in `<root>/.meta.db`. Per-key atomicity comes from Couchbase's own CAS, so the `cas` strategy's reference counting behaves exactly as it does on the embedded store — two concurrent identical uploads still yield one blob with two references — and the GC sweep needs no election layer or extra configuration when several replicas run it at once: the claim step is itself compare-and-set, so each blob is collected exactly once and the losing sweeper simply moves on. Rows are namespaced by driver name, so several drivers may share one connectors entry without colliding, which matters under `cas` where identical bytes always mint the same key. The two secondary indexes the maintenance verbs need are created at boot when missing; if the account may not create them the boot still succeeds and the exact `CREATE INDEX` statements are logged to run by hand, because Couchbase errors on an unindexed query rather than merely running it slowly. Inline payloads are stored base64-encoded inside the document (Couchbase cannot query a binary value), which costs about a third more space and puts a practical ceiling near a 14MB `inlineThreshold`. Mutations use the SDK's default durability unless the entry sets `durability` to `majority`, `majorityAndPersistToActive` or `persistToMajority`.
+* A third storage strategy, `stream`, for large sequential media — and with it resumable uploads. Set `"strategy": "stream"` on a driver and keys name an ASSET rather than a file (`assets/<ulid>/original<ext>`), so an object and anything later derived from it live in one directory you can move or delete as a unit; keys stay opaque as under every strategy. Alongside the usual `put()`, a stream driver carries five more verbs, gated by `capabilities.resumable`: `createUpload()` opens a session, `writeSegment()` writes one segment AT A BYTE OFFSET — segments may arrive out of order and in parallel, and re-sending a range that already landed is harmless — `statUpload()` reports what arrived and, crucially, what is still MISSING, `finalize()` publishes, and `abortUpload()` throws the session away. A session survives a bundle restart: its state lives in the driver root, not in memory. `createUpload()` REQUIRES the object's total size, and that is a deliberate limit rather than an oversight — without a declared total nothing can verify that the received ranges actually cover the object, and `statUpload()` could only report what arrived, never what is missing; upload of unknown-size content stays `put()`'s job. Finalise verifies coverage as an interval UNION and refuses to publish a gap, keeping the session alive so a client can complete it. That check is the feature's whole safety story: an unwritten range in the assembling file reads back as ZEROS rather than failing, so a finalise that merely added up what it received — two segments overlapping in the middle can sum to the full size while leaving the tail untouched — would publish a plausible object with silently wrong bytes. Finalise is also idempotent: if it published the bytes and then failed to index them, calling it again completes the job instead of wedging. Segments are fsynced before they are recorded as durable (`fsync` defaults to true here, as it does for `cas`), so a client is never told a range is safe when it is not; on a fast LAN, where that flush costs more than the transfer, set `fsync: false` and accept the documented power-loss window. Three new per-driver keys, all optional: `chunkSize` (default `"8MB"`, the segment size the write path is tuned for and the one `createUpload()` reports back), `sessionTtl` (default `"24h"`) and `sessionSweepInterval` (default `"1h"`) — abandoned sessions are reclaimed on their own age-gated sweep, which runs at boot and periodically, and also clears temp files left behind by a crashed `put()`. A stream driver does not tier and does not hash, so `inlineThreshold` and `hash` are reported as ignored keys there rather than silently doing nothing. `getRange()` works as it does everywhere else, and — as with the other strategies — `self.serveFromStorage()` serves it over HTTP with `206`/`416` and `Accept-Ranges`/`Content-Range` on both engines. Not included, deliberately: renditions beside `original` (the layout reserves the room, there is no API yet), post-hoc checksums, and any `storage:gc` / `storage:verify` support for stream, which remain `cas`-only. Parallel writes from several processes are safe when their ranges do not overlap on a POSIX-coherent filesystem; on a relaxed-coherence network mount, route one session's segments to one process. Configuring `stream` no longer refuses the boot as a not-yet-implemented strategy.
+* Storage read-verb errors now carry a machine-readable err.code — STORAGE_NO_OBJECT (unknown, released or vanished key), STORAGE_RANGE_UNSATISFIABLE (a range start at or beyond the object size, the caller's 416) and STORAGE_INVALID_RANGE (malformed bounds) — on get()/getRange()/resolve() across all three local strategies — and the `s3` adapter, shipping in this same release, maps its provider errors onto the same codes — so an HTTP serving layer can map 404/416/400 without parsing message text. Message wording is byte-unchanged.
+* HTTP Range serving for stored objects. self.serveFromStorage(driverName, key[, opts]) is the read-side companion of store()'s driver routing and owns the whole protocol dance on both engines: stat()-gated 404s, a strong ETag minted from the immutable storage key plus Last-Modified from the publish time, conditional GET (If-None-Match, weak-compared, answers 304 with no driver read), and single-range bytes= evaluation gated on driver.capabilities.ranges — a satisfiable a-b / a- / -n range answers 206 with Content-Range and an exact Content-Length, an unsatisfiable one answers 416 with Content-Range bytes */<size>, and multi-range lists, foreign units and syntactic garbage are ignored into the full 200 as RFC 9110 sanctions, with If-Range honouring the Range only on an exact validator match (fail-safe to the full body). Accept-Ranges is advertised whenever the driver can serve ranges; every response carries X-Content-Type-Options nosniff; the uploader-supplied stored contentType downgrades to application/octet-stream for active-content types (html/xml/svg/javascript) unless the app passes an explicit opts.contentType; caching defaults to private, max-age=31536000, immutable — keys are immutable — with opts.cacheControl winning verbatim; opts.download/opts.filename emit an RFC 6266 attachment disposition with control characters stripped from the stored name. HEAD answers headers-only. (On an offload-capable driver — the `s3` adapter, shipping in this same release — GET and HEAD redirect to a presigned URL instead of streaming in-process; see that entry.)
+* Soak probes for the Couchbase metadata store behind the object-storage layer now ship in the package, at `script/soak/storage-couchbase/` — beside the existing `couchbase-soak.js`, and operator-invoked in the same way. They exist because the unit suite drives a fake SDK that pattern-matches statement shapes without ever parsing N1QL or evaluating a compare-and-swap, so a whole class of defect is invisible to it: a reserved word in a statement reached a release that way. `probe-cas.js` needs no framework code at all and reports the error class a stale-CAS `mutateIn` actually raises on your server, using two genuinely separate connections and a fresh-CAS positive control so a throw cannot be mistaken for a bad path or a missing permission. `probe-store.js` drives the store itself and covers an identical-put storm (run it cross-process for the real case), zero-reference accounting, the barrier race on the CAS claim, and the sweep path near its grace boundary. Everything is configured by environment variable, so nothing is pinned to a particular deployment. Requires a reachable cluster, a bucket and index-create rights; deliberately never run in CI, which has no cluster.
+* The `s3` storage adapter — the last step of the pluggable object-storage layer (#STO1): `adapter: 's3'` plus a `bucket` in a `settings.json > storage` driver stores objects on any S3-compatible provider (AWS S3, Scaleway, MinIO, R2…) under the sharded key grammar, namespaced by an optional `prefix`. Storeless by design: the provider carries each object's metadata on the object itself (Content-Type, plus the original name as URI-encoded user metadata — immutable after upload, like the key), so there is no metadata store, no tiering, and no drift class to verify; `stat()` is a strongly-consistent HeadObject, and the docs ship the minimal IAM policy (without `s3:ListBucket`, a missing key answers 403 instead of 404). The SDK stays the PROJECT's dependency — the connector policy: install `@aws-sdk/client-s3`, `@aws-sdk/lib-storage` and `@aws-sdk/s3-request-presigner` in your project, and a configured s3 driver whose SDK is missing refuses the boot with that hint. `resolve()` answers the contract's reserved `{kind: 'url'}` with a presigned GET (`presignExpiry`, default `'15m'`) and gains an optional middle `opts` argument carrying response overrides (`contentType`/`download`/`filename`/`cacheControl` → the provider's signed `response-*` params; local strategies accept and ignore it). `capabilities.offload` flips true for the first time and `self.serveFromStorage()` becomes its first consumer: GET/HEAD answer 307 to the presigned URL — after the local If-None-Match 304 check, with the fail-closed content-type downgrade riding the signed `response-content-type` so the stored-XSS guard holds when the provider serves the bytes, and with Range answered natively by the provider — while `opts.offload: false` keeps the in-process proxy path (`get`/`getRange` are real). Static credentials (`accessKeyId`/`secretAccessKey`, `${secret:KEY}`-friendly) are optional: omitted, the SDK default provider chain (env / shared config / IMDS / IRSA) runs. A build-time age-gated sweep aborts incomplete multipart uploads older than `sweepGrace` — they bill storage until aborted, the s3 analog of a crashed-put temp file — with a bucket lifecycle rule recommended as defense-in-depth. `cas`/`stream` refuse the s3 adapter at boot with an explanation (the provider owns placement), and the `storage:*` CLI names s3 drivers as remote, skipping them offline.
+### Changed
+* renderStream() is now byte-serving-capable, the engine-side groundwork for HTTP Range on stored objects: on non-SSE content-types, Buffer chunks pass through verbatim instead of being UTF-8-decoded (binary payloads previously arrived corrupted — every invalid-UTF-8 byte replaced with U+FFFD; valid-UTF-8 Buffers re-encode byte-identically, so text consumers are unaffected and SSE keeps its decode); HEAD requests answer headers-only without consuming the iterable, the same render-layer body suppression every other delegate already honours (a destroyable source is destroy()ed instead of leaking its handle); and the delegate's default headers (cache-control, connection, x-accel-buffering) now yield to values the caller pre-set instead of silently clobbering them on both engines.
+### Fixed
+* renderStream() now honours a caller-set response status on BOTH engines (#B351). The HTTP/2 arm built its `stream.respond()` frame with a hardcoded `':status': 200` pseudo-header, and the HTTP/1.1 arm assigned `response.statusCode = 200` unconditionally inside its not-yet-sent block, clobbering a code the controller had already chosen — so renderStream could only ever answer 200 and `206 Partial Content`, `416` and `404` were unreachable through it on either engine. Both arms now resolve `response.statusCode || 200`, so a controller may pre-set the status before streaming; the 200 fallback is unchanged when none is set, and the pending-header merge still refuses to overwrite `:status`. Same defect class as #B172 (render-json): a hand-built HTTP/2 frame must never carry a literal status, because `setHeader(':status', …)` throws and no later merge can repair a pseudo-header.
+* A redirect route no longer discards the caller's query string when it declares `keep-params: true`, and the redirect gina generates for a non-root `server.webroot` now sets that flag itself (#B352). Previously a bare-webroot request such as `/dashboard?token=abc` was answered `302 /dashboard/` with the parameter gone, so any flow carrying a signed token, a redirect target or any other parameter into a bundle lost it whenever the URL was written without a trailing slash — the application saw an absent value rather than a bad link, and nothing on screen or in its own logs pointed at the URL. `keep-params` had been documented as a redirect-route key since before the project moved to GitHub but was never implemented: the value was read and then dropped, so every `control: "redirect"` route silently discarded the query. It is now honoured, and still defaults to false — existing redirect routes are unaffected. Only a local target inherits the query: an absolute `param.url` names another origin, so the flag is ignored there rather than disclosing the caller's parameters to a third party, and CR/LF are stripped so a crafted query cannot split the `Location` header. Note that setting `webrootAutoredirect` to false never avoided this loss — that setting only controls whether the site root also redirects to the webroot; the bare-webroot redirect happens either way.
+* A redirect no longer treats HEAD as a wrong method (#B353). HEAD is a safe method — GET without a response body — but the guard that stops an unsafe method being replayed against a redirect target tested only for GET, so HEAD was handled like POST or PUT: it drew a "trying to redirect using the wrong method" warning even on a route that explicitly lists HEAD among its own methods, it was answered 303 (telling the client to re-issue as GET and fetch a body it had deliberately not asked for), and because the method was switched it also received a copy of the request parameters that the same request as a GET never gets — carried through the session where one is mounted, or appended to the redirect target in clear as the session-less fallback. HEAD is now admitted alongside GET, so it behaves exactly as GET does: the route's configured status code, the same Location, and no warning. Unsafe methods are unchanged — POST, PUT and DELETE still get the warning, the switch to GET and the 303. Note this is wire-visible: a HEAD request against a redirect route now answers the route's own code (302 for the framework-generated webroot redirect) rather than 303, so a monitor asserting 303 on a HEAD health-check needs adjusting.
+* renderStream() no longer throws a swallowed TypeError at the end of every streamed response: the post-end headersSent bookkeeping assignment hits a getter-only accessor on real response objects under strict mode, detouring each stream through a late error path and silently dropping the Inspector Flow timeline's stream-write/total entries. The wire output was always correct — the timeline now survives, and the assignment is guarded on both engine arms.
+* A refused or interrupted `put()` no longer leaves a stray temp file behind in a local storage root. `fs.createWriteStream()` opens ASYNCHRONOUSLY, so a put that failed early — refused for exceeding `maxObjectSize`, or because the source errored just as the object spilled from the inline tier out to a file — could run its cleanup while the file was still being created, find nothing there, skip the unlink, and orphan the `.tmp` entry that appeared a moment later. Cleanup now waits for the write stream to close before the failure is reported, so a caller told the put failed can rely on nothing having been left behind. All three local strategies are fixed. Orphans that predate this release are cleaned up for you: the same release teaches `sharded` to reclaim abandoned temps at build time, which it previously never did, so starting the bundle clears anything older than the grace window.
+* A `sharded` storage driver now reclaims temp files left behind by a `put()` whose PROCESS died, instead of accumulating them forever. `cas` has always done this at build and `stream` has its own age-gated pass, which left `sharded` as the one strategy where the leak was permanent — no verb ever looked at those files again, so the only cure was deleting them by hand. The sweep runs at build time, which is both the right trigger and the only safe one: a restart is the earliest moment the previous process is provably gone. It is gated on `sweepGrace`, the same key, default (`"1h"`) and meaning `cas` already uses, which is now accepted on a `sharded` driver rather than warned about as an ignored key. Only temps older than the grace are touched — on a root shared by several bundles or replicas a fresh temp may be a sibling process's live write, and eating it would corrupt a put in flight. `sweepInterval` deliberately stays `cas`-only: `sharded` sweeps at build and has no periodic pass to configure. Nothing to turn on, and no migration — if you have orphans from before this release, starting the bundle clears the ones past the grace.
+### Security
+* self.push() chose its recipient from the request body, so a caller could aim a push at any session by sending a session id — and omitting that id broadcast the payload to EVERY connected client. The payload itself also defaults to request input, so on any route that reaches push() an unprivileged caller could deliver arbitrary content to every connected socket, or to a chosen victim's socket. This affects every release up to and including 0.6.7. The recipient is now decided server-side: an explicit option.sessionID wins, otherwise the payload goes to the caller's own session; with neither a resolvable session nor a deliberate { broadcast: true }, push() now sends nothing and warns, where it previously fell open to everybody. The request body can no longer influence the recipient at all. A type guard that compared a negated constructor name against a string — always false, so it had never once skipped a non-socket entry — was corrected in the same pass. ACTION REQUIRED, and read this before upgrading if you push at all: any route that called a bare self.push() and relied on the request choosing the recipient now resolves to the caller's own session, so a push driven over an HTTP hop by a background worker — a job runner reporting progress to the user who queued it, threading that user's session id through the request — stops delivering and warns instead. That pattern is exactly the vulnerability, so it cannot be preserved; but be aware the framework does not yet offer a sanctioned replacement for it. push() is reachable only from a live request-bound controller (it returns early once the request is released) and nothing else can reach the socket set, so there is no in-process call a worker can make instead. Until an explicit out-of-request push channel exists, out-of-request progress must go through polling GET /_gina/jobs/:id, or through a transport your application owns. In-request callers are unaffected unless they depended on the implicit fan-out, which now needs { broadcast: true }.
+* Request headers were spliced unescaped into the client bootstrap script gina emits on every rendered page, allowing reflected script injection. `X-Forwarded-Host`, `X-Forwarded-Proto`, `X-Forwarded-Prefix` and the request's own `Host` reached JavaScript string literals in that script — the values behind `gina.config.hostname`, `gina.config.webroot` and `window.__ginaWebroot` — with no escaping applied, so a header containing a single quote closed the literal and ran attacker-chosen script in the browser of anyone served that page. It needed no authentication and applied to any route that renders a view. This affects every release up to and including 0.6.7, and was reproduced end to end over HTTP. Forwarded values are now validated where they are read, in both the Isaac engine and the engine-agnostic router: a host must be a hostname with an optional port or a bracketed IPv6 literal, a forwarded scheme must be exactly `http` or `https`, and a forwarded path prefix must consist of URL-path characters only. Anything else is rejected and the request falls back to the bundle's own configured host and webroot, exactly as if the header had never been sent. Validating at ingest rather than escaping at output means every consumer of these values is protected, not only the bootstrap script. Whether a deployment was reachable depended on its proxy: one that sets or strips the `X-Forwarded-*` headers it forwards never passed an injected value through, while a bundle exposed directly, or sitting behind a proxy that relays client headers verbatim, could be driven by any anonymous caller. No action is required beyond upgrading — no configuration changes, no application code changes, and a deployment whose proxy sends a well-formed host, scheme and prefix behaves identically. Two small behaviour corrections ride along: a request whose `Host` or `X-Forwarded-Host` is malformed is no longer classified as proxied at all, and an absent `X-Forwarded-Proto` no longer produces a literal `undefined://` prefix on the whispered origin. Pickup is a bundle restart; the browser bundle is unchanged, so no rebuild is needed.
+
 ## 0.6.7 - 2026-08-13
 ### Added
 * Pluggable object storage. A storage block in settings.json declares named drivers (an adapter crossed with a strategy), and gina.storage() returns one. The local adapter with the sharded strategy stores every object atomically under a date-and-ULID key — as a published file, or inline in the metadata store when the object is smaller than the driver's size-tiering threshold — and records its metadata (original name, content type, size) through a pluggable store seam - an embedded SQLite file by default, or a connectors.json entry when several processes share one root. Storage keys are opaque, so a later layout change cannot break stored references. A driver root that sits inside a web-served directory refuses the boot, since objects there would be publicly fetchable.

package/README.md

@@ -29,6 +29,7 @@ MVC framework for Node.js and Bun with built-in HTTP/2, multi-bundle architectur
 | DTOs | `gina.dto` schema builder — request validation with localised 422s (`param.dto`), response shaping (`param.responseDto`), JSON Schema export |
 | Sessions | Hardened session plugin (SameSite / HttpOnly / Secure defaults) — Redis, SQLite, MongoDB, Couchbase, and ScyllaDB stores; session-id rotation on login, opt-in absolute timeout, record destroyed on logout |
 | File uploads | Multipart via the maintained [`@rhinostone/busboy`](https://github.com/gina-io/busboy) fork — named upload groups with per-group extension allow-lists, size / count limits, and target dirs |
+| Object storage | `gina.storage()` — named drivers pairing an adapter (`local` filesystem, or `s3` for any S3-compatible provider with its SDK as a project-side dependency) with a key strategy behind opaque keys: `sharded` (dated), `cas` (content-addressed, deduplicating, refcounted, GC-swept) and `stream` (large media, resumable out-of-order segment uploads); size tiering, HTTP Range serving (`serveFromStorage()` — 206/416/304, strong key ETags), presigned-URL offload (307) on `s3`, embedded SQLite or Couchbase metadata store, `storage:stats` / `gc` / `verify` CLI |
 | Async jobs | `self.startJob()` background jobs — durable SQLite / MongoDB / Redis stores, retries with backoff, HMAC-signed completion webhooks, `/_gina/jobs/:id` status endpoint |
 | Response caching | Per-route render cache — memory / fs / Redis tiers, cross-replica warm start, event-driven invalidation, RFC 9211 `Cache-Status` |
 | Authentication | `lib.authn` primitives — scrypt password hashing as self-describing PHC strings (argon2 / bcrypt verify-only for migration), NIST SP 800-63B policy, enumeration-safe `dummyVerify`, PCI-DSS account lockout, RFC 6238 TOTP |
@@ -60,38 +61,38 @@ open https://localhost:3100
 
 > **npm 12+** blocks install scripts by default, and gina's post-install bootstraps `~/.gina` and the framework dependencies. Install with `npm install -g gina@latest --allow-scripts=gina`, or allow it once for all global installs with `npm config set allow-scripts=gina --location=user`. (Not needed on npm ≤ 11.)
 
-## What's in 0.6.7
+## What's in 0.6.8
 
-> **Re-bake your bundles, not just restart them.** The browser bundle changed in
-> this release. The form-validation, styling and link fixes below live in the
-> bundle, so a restart alone will not deliver them. Rebuild each bundle
-> (`gina bundle:build`) as well as restarting. The storage layer and the
-> instrumentation change are server-side and need only the restart.
+> **Restart your bundles — no re-bake this time.** The browser bundle is
+> byte-identical to `0.6.7`, so `gina bundle:restart` is enough; everything below
+> is server-side. (`0.6.7` did need the rebuild — this one does not.)
 
-> **No settings reset.** `0.6.7` is a patch — the `shortVersion` stays `0.6`, so
+> **No settings reset.** `0.6.8` is a patch — the `shortVersion` stays `0.6`, so
 > your `~/.gina/0.6/settings.json` is untouched. (`0.6.0` was the reset.)
 
-**One item requires action before you upgrade:** the `is` validation rule now
-compiles regex literals as authored, which makes any pattern containing
-parentheses *stricter* than it was. Two more may need a look — `req.files[].group`
-now reports `untagged` instead of `undefined`, and bound query parameter values
-are redacted from dev logs by default. All are called out below and in the
+**This release fixes two security flaws, and both were live in every published
+version up to and including `0.6.7`.** One of them changes behaviour you may be
+relying on: `self.push()` no longer lets the request choose who receives a push,
+which stops a pattern some applications use to report background-job progress.
+Read that entry before upgrading. Both are covered in the
 [migration guide](https://gina.io/docs/migration).
 
-- **Added — pluggable object storage.** A new optional `storage` block in `settings.json` declares named drivers — an *adapter* (where bytes live) crossed with a *strategy* (how keys are laid out) — reachable from application code as `gina.storage()`. Objects are published atomically under an opaque key, with their metadata recorded through a pluggable store seam. A driver root that sits inside a web-served directory refuses the boot, since objects there would be publicly fetchable without passing your authorization. With no `storage` block the whole feature is inert. See the [storage guide](https://gina.io/docs/guides/storage).
-- **Added — content-addressed storage (`strategy: "cas"`).** Keys derived from the object's digest, so identical bytes stored twice yield the same key and no second copy — the blob gains a reference instead. `release()` drops a reference rather than deleting, and a grace-gated sweep reclaims blobs that have sat at zero. `findByDigest()` answers whether content is already stored without transferring it. cas publishes `fsync` by default, because the strategy exists for immutable content.
-- **Added — size tiering.** Objects strictly under a driver's `inlineThreshold` (default `"64KB"`, the measured knee) are stored inline in the metadata store in a single transaction rather than as individual files — 2.7–13× faster than per-file writes at and below the default. Keys, `stat()` and `release()` are identical in both tiers. Two tradeoffs worth knowing: sub-threshold objects are not individually browsable on disk, and the metadata store then carries their bytes. Set `"0B"` per driver to turn it off.
-- **Added — storage maintenance CLI.** `gina storage:stats`, `storage:gc` (`--dry-run`) and `storage:verify` (`--fix`) follow whoever owns the store: a running bundle answers through new always-on, admin-gated `/_gina/storage/*` endpoints, a stopped one is opened offline, and an unreachable one is never touched. `verify` separates fixable sweep residue from loss evidence, and never auto-fixes the latter.
-- **Added — upload groups can publish into a storage driver.** A `driver` key on an `upload` group routes that group's `self.store()` step through the named driver instead of moving files to the target directory. Entirely opt-in and per-group: groups without a `driver` keep the historical move path byte-for-byte. Routed entries come back with an opaque `key` and no `filename`.
-- **Security — bound query parameter values are redacted by default.** Dev-mode console query lines, the Couchbase `bulkInsert` statement, the MongoDB resolved body and the Inspector query log no longer print bound parameter values; they carry count and type markers instead (`3 [string, number, string]`). A bind value is routinely a secret owned by your application — a session or credential token, an API key, a password hash — and a positional bind array has no key names, so the key-based `inspector.redact` matching structurally could not cover it. **Set `inspector.queries.captureValues` to `true`** if your debugging workflow needs the real values back.
-- **Fixed — `is` regex literals compile as authored.** A security transform stripped every `(`, `)` and literal `return` from a regex-literal condition *before* compiling it, silently changing what the pattern matched: `/^(a|b)$/` behaved as `/^a|b$/`, accepting any value merely containing a middle alternative, and `(#TAG)?` became a literal `#TA` plus an optional `G`. The transform now applies only to the binary-comparison form, which keeps its grammar-locked protection. **Action required:** review `is` rules whose pattern contains parentheses — they now match as authored, i.e. stricter, so values that were passing only through the mangled pattern will start failing.
-- **Fixed — forms with an async `query` rule complete correctly.** A cluster of interacting defects, each of which masked the others: a submit could leave before the query answered (with its error rendering after the POST); the completion carried only the query field's verdict, so other invalid fields were adjudicated but never shown; a re-click on an unchanged value cleared later fields' errors, with the outcome depending on field declaration order; a clean form whose query field was not declared last could never submit at all, stranding its re-entry latch and swallowing every later click until reload; stale listeners could replay a submit; and a submit trigger with no markup `id` was bound twice, running two validation cycles per click. A submit gesture landing while a live-check query is still on the wire now waits for the verdict instead of being silently refused.
-- **Changed — framework default looks ship in a CSS cascade layer.** The defaults for `data-gina-loading` and `data-gina-form-submit-gated` now live inside `@layer gina`, so any un-layered project rule beats them regardless of specificity or load order — no `!important` needed. Functional rules (popin structure, scroll lock) deliberately stay un-layered so a generic project reset cannot break them. If your project organises its own CSS in layers, declare `@layer gina, app;` early to order yourself against gina explicitly.
-- **Fixed — `getConfig().settings` resolves path placeholders.** A settings value written with `${bundlePath}`, `${publicPath}`, `${gina}`, `${<name>Port}` and friends reached the no-argument `getConfig()` surface as a literal token, because that alias was bound before the substitution pass and the pass returns a new object. It now agrees with `getConfig().content.settings`. `${secret:…}` references were never affected.
-- **Fixed — `req.files[].group` carries the resolved upload group.** The parser always resolved each part's group — no tag resolves to `untagged` — but pushed the raw disposition parameter into the record, so the field was `undefined` in exactly the default case. **Code shaped like `if (file.group)` now enters the branch for untagged files** where it previously skipped them.
-- **Fixed — the settings template stopped advertising upload keys the framework never read.** The per-group `filePrefix`, `subFolder` and `maxFieldsSize` samples and the block-level `encoding` key were shipped as scaffolding samples and documented as functional, and no code path read any of them. They are retired from the template, the reference page is corrected, and `schema/settings.json` now declares the real key set. Applications declaring their own per-group keys and applying them app-side are unaffected.
-- **Fixed — the Inspector shows your data, not the framework's.** The Data tab no longer lists the `__ginaFlow` and `__ginaQueries` transport keys, which the Query and Flow tabs already present first-class; any root key prefixed `__gina` is hidden across every Data surface, while nested keys carrying the prefix stay visible as application data. The Forms tab demotes the bundle's forms catalog into a single collapsed **Bundle catalog** card at the bottom, so the page's real forms keep the prime space.
-
+- **Security — `self.push()` decides its own recipient.** The recipient was read from the request body, so a caller could aim a push at any session by sending a session id — and omitting that id broadcast to *every* connected client. The payload defaults to request input too, so on any route reaching `push()` an unprivileged caller could deliver arbitrary content to everyone, or to a chosen victim. The recipient is now decided server-side: an explicit `option.sessionID` wins, otherwise the caller's own session; with neither a resolvable session nor a deliberate `{ broadcast: true }`, `push()` sends nothing and warns, where it previously fell open to everybody. The request body can no longer influence the recipient at all. **Action required if you push at all:** a bare `self.push()` driven over an HTTP hop by a background worker — a job runner reporting progress to the user who queued it, threading that user's session id through the request — now resolves to the caller's own session and stops delivering. That pattern *is* the vulnerability, so it cannot be preserved; but be aware there is no in-process substitute yet, because `push()` is reachable only from a live request-bound controller. Until an explicit out-of-request channel exists, poll `GET /_gina/jobs/:id` or use a transport your application owns. In-request callers are unaffected unless they relied on the implicit fan-out, which now needs `{ broadcast: true }`.
+- **Security — forwarded headers can no longer inject script.** `X-Forwarded-Host`, `X-Forwarded-Proto`, `X-Forwarded-Prefix` and the request's own `Host` were spliced unescaped into the client bootstrap script gina emits on every rendered page, landing inside JavaScript string literals. A header containing a single quote closed the literal and ran attacker-chosen script in the browser of anyone served that page — no authentication, any route that renders a view. Forwarded values are now validated where they are read: a host must be a hostname with an optional port or a bracketed IPv6 literal, a scheme must be exactly `http` or `https`, and a path prefix must be URL-path characters only. Anything else is refused and the request falls back to the bundle's own configured host and webroot, exactly as if the header had never been sent. Whether you were reachable depended on your proxy — one that sets or strips the `X-Forwarded-*` headers it forwards never passed an injected value through, while a bundle exposed directly, or behind a proxy relaying client headers verbatim, could be driven by any anonymous caller. No action beyond upgrading; a well-formed host, scheme and prefix behave identically.
+- **Added — storage metadata on Couchbase, which makes a driver root shareable.** The embedded SQLite store is single-process-per-root, so two bundles — or two replicas of one — could not share a root until now. Point a driver's `store` at a `connectors.json` entry whose connector is `couchbase` and every metadata row, inline payloads included, lives on the cluster. Per-key atomicity comes from Couchbase's own CAS, so `cas` reference counting behaves exactly as on the embedded store, and the GC sweep needs no election layer when several replicas run it at once — the claim step is itself compare-and-set, so each blob is collected exactly once. Rows are namespaced by driver name. The two secondary indexes the maintenance verbs need are created at boot when missing; if the account may not create them the boot still succeeds and the exact `CREATE INDEX` statements are logged. Inline payloads are base64-encoded inside the document, which costs about a third more space and puts a practical ceiling near a 14MB `inlineThreshold`.
+- **Added — a `stream` strategy for large sequential media, with resumable uploads.** Keys name an *asset* rather than a file (`assets/<ulid>/original<ext>`), so an object and anything later derived from it live in one directory you can move or delete as a unit. Alongside `put()`, a stream driver carries `createUpload()`, `writeSegment()` (at a byte offset — segments may arrive out of order and in parallel, and re-sending a landed range is harmless), `statUpload()` (which reports what is still *missing*), `finalize()` and `abortUpload()`. Sessions survive a restart. `createUpload()` requires the object's total size deliberately: without it nothing can verify the received ranges actually cover the object. Finalise checks coverage as an interval union and refuses to publish a gap — an unwritten range reads back as zeros rather than failing, so a finalise that merely summed what it received could publish a plausible object with silently wrong bytes. Finalise is idempotent. New optional per-driver keys: `chunkSize` (default `"8MB"`), `sessionTtl` (`"24h"`) and `sessionSweepInterval` (`"1h"`).
+- **Added — HTTP Range serving for stored objects.** `self.serveFromStorage(driverName, key[, opts])` is the read-side companion of `store()`'s driver routing, and owns the whole protocol dance on both engines: `stat()`-gated 404s, a strong ETag minted from the immutable storage key, conditional GET answering 304 with no driver read, and single-range `bytes=` evaluation — a satisfiable range answers 206 with an exact `Content-Length`, an unsatisfiable one 416, and multi-range lists, foreign units and syntactic garbage fall back to the full 200 as RFC 9110 sanctions. Every response carries `X-Content-Type-Options: nosniff`, and a stored `contentType` for active-content types (html/xml/svg/javascript) downgrades to `application/octet-stream` unless you pass an explicit `opts.contentType`. `opts.download`/`opts.filename` emit an RFC 6266 attachment disposition.
+- **Added — the `s3` storage adapter, completing the pluggable object-storage layer.** `adapter: 's3'` plus a `bucket` stores objects on any S3-compatible provider (AWS S3, Scaleway, MinIO, R2…) under the sharded key grammar. Storeless by design: the provider carries each object's metadata on the object itself, so there is no metadata store, no tiering and no drift class to verify. The SDK stays your project's dependency — install `@aws-sdk/client-s3`, `@aws-sdk/lib-storage` and `@aws-sdk/s3-request-presigner`; a configured s3 driver whose SDK is missing refuses the boot with that hint. `resolve()` answers `{kind: 'url'}` with a presigned GET, and `capabilities.offload` flips true for the first time: `serveFromStorage()` answers GET/HEAD with a 307 to the presigned URL — after the local 304 check, with the content-type downgrade riding the signed `response-content-type` so the stored-XSS guard holds when the provider serves the bytes. `opts.offload: false` keeps the in-process proxy path. Static credentials are optional; omitted, the SDK's default provider chain runs.
+- **Added — storage drivers can read a byte range.** `getRange(key, start, end, cb)` ships on every local strategy (`sharded`, `cas`, `stream`), returning a readable stream over the requested slice.
+- **Added — machine-readable storage read errors.** Read-verb failures now carry `err.code` — `STORAGE_NO_OBJECT` for an unknown, released or vanished key, and siblings for the other classes — so callers can branch on the cause instead of matching message text.
+- **Added — Couchbase soak probes ship in the package.** The soak probes for the Couchbase metadata store live at `script/soak/storage/`, so you can exercise a cluster-backed driver root against your own deployment rather than trusting ours.
+- **Changed — `renderStream()` is byte-serving-capable.** On non-SSE content types, `Buffer` chunks now pass through verbatim instead of being UTF-8-decoded — binary payloads previously arrived corrupted, with every invalid-UTF-8 byte replaced by U+FFFD. Valid-UTF-8 buffers re-encode byte-identically, so text consumers are unaffected, and SSE keeps its decode. HEAD requests answer headers-only without consuming the iterable (a destroyable source is destroyed rather than leaking its handle), and the delegate's default headers now yield to values the caller pre-set instead of clobbering them.
+- **Fixed — `renderStream()` honours a caller-set status code on both engines.** The HTTP/2 arm built its response headers before the caller's status was read, so a streamed 206 or 404 went out as 200.
+- **Fixed — `renderStream()` no longer throws a swallowed `TypeError` at the end of every streamed response.** The post-end `headersSent` bookkeeping ran against a response object that no longer accepted it.
+- **Fixed — a redirect no longer treats `HEAD` as a wrong method.** `HEAD` is a safe method — `GET` without a response body — but the redirect path rejected it as if it were a write.
+- **Fixed — a redirect keeps the caller's query string under `keep-params: true`.** The declared parameters were carried but the query string was dropped.
+- **Fixed — a `sharded` driver reclaims temp files left by a crashed `put()`.** A `put()` whose *process* died left its temp file behind to accumulate forever; an age-gated best-effort sweep now clears them.
+- **Fixed — a refused or interrupted `put()` leaves no temp residue.** The stray temp file a rejected write left in a local storage root is now removed on the failure path.
 ## Documentation
 
 Full installation guide, tutorials, configuration reference, and API docs at **[gina.io/docs](https://gina.io/docs/)**.

package/ROADMAP.md

@@ -59,6 +59,7 @@ This roadmap covers planned features, architectural improvements, new connectors
 | **Q4 2026** | `0.6.5` ✅ | **Fixed**: the silent-dead-control release — a family of defects where a control looked completely normal and did nothing at all. A submit trigger disabled by your own double-submit guard during the click (a `0.6.4` regression), a submit button whose DOM node an AJAX update or popin re-render replaced, a form left blocked after its async uniqueness check came back clean, a popin close button given your own id or wrapping an icon, a `data-gina-link` given your own id, and a popin holding several forms releasing only every other one — all now work. Trusted gestures (Enter, wrapped-label clicks) respect the submit gate; `data-gina-link` stops swallowing `download`, `target`, `#`-fragment and modified clicks, and gains the disabled gate it never had; download filenames parse and serialize per RFC 6266; `gina.setOptions()` writes the config the framework reads, having been silently ignored since it shipped; `isRequired` accepts padded input and `trim` strips both sides · **Changed**: the not-ready submit-trigger state moves off `aria-disabled` onto the framework-owned `data-gina-form-submit-gated`, with a default look — the marker no longer claims a control is inoperable while gina deliberately answers its click |
 | **Q4 2026** | `0.6.6` ✅ | **Fixed**: the logging-transport release. A slow boot no longer silences a bundle's logging for the life of the process — a two-second connect deadline added in `0.6.5` read a socket flag Node clears one event-loop phase later, so any boot that blocked the loop past it destroyed a connection the kernel had already established (every container start and network-filesystem mount was exposed, and the transport never redialled). The MQ and file log transports also stopped dialling `host_v4`, which on a `~/.gina` shared across hosts silently shipped every log line off-host while all connection lines read healthy. Plus: the popin `success` event fires again instead of raising a 422 carrying the successful response body; a link request belongs to the anchor you clicked rather than the first anchor sharing its url; and constructing the link handler twice no longer corrupts the first instance · **Added**: the log transport reconnects — exponential backoff to a 30-second ceiling, one report per outage, frames dropped rather than queued while down so an outage cannot grow memory |
 | **Q4 2026** | `0.6.7` ✅ | **Added**: the object-storage release — a `storage` block declares named drivers (an adapter crossed with a strategy) reachable as `gina.storage()`, publishing objects atomically under opaque keys with their metadata written through a pluggable store seam; a content-addressed `cas` strategy deduplicates identical bytes behind a reference count, reclaiming them only after a grace-gated sweep; size tiering keeps sub-`64KB` objects inline in the metadata store, measurably faster than per-file writes; `storage:stats` / `storage:gc` / `storage:verify` operate a bundle's drivers whether it is running or stopped, through always-on admin-gated endpoints; and an upload group can route its `self.store()` step straight into a driver · **Security**: bound query parameter values no longer reach dev consoles or the Inspector query log — count and type markers replace them, with `inspector.queries.captureValues` to opt back in · **Fixed**: the `is` rule compiles regex literals as authored instead of stripping their parentheses (stricter — review patterns containing parens), forms with an async `query` rule complete correctly across a cluster of interacting defects (a submit leaving before the verdict landed, a completion carrying only the query field's slice, a re-click clearing later fields' errors, a clean form whose query field was not declared last never submitting at all, replayed submits from stale listeners, and an id-less trigger bound twice), `getConfig().settings` resolves path placeholders, `req.files[].group` reports the resolved group instead of `undefined`, and the Inspector's Data and Forms tabs stop putting framework-internal keys and the bundle catalog above your own data · **Changed**: framework default looks ship inside a `@layer gina` cascade layer, so any un-layered project rule overrides them without `!important` |
+| **Q4 2026** | `0.6.8` ✅ | **Security**: `self.push()` decides its recipient server-side instead of reading it from the request, where a supplied session id aimed the push at any session and an absent one broadcast to every connected client (ACTION REQUIRED — a background worker pushing over an HTTP hop stops delivering; poll `GET /_gina/jobs/:id` in the meantime) · forwarded headers (`X-Forwarded-Host`, `-Proto`, `-Prefix` and the request's own `Host`) are validated where they are read, closing a reflected-XSS path that spliced them unescaped into the client bootstrap script emitted on every rendered page · **Added**: storage metadata can live on Couchbase, which is what makes a driver root shareable across bundles and replicas; a `stream` strategy for large sequential media brings resumable, out-of-order, restart-surviving uploads whose finalise verifies coverage as an interval union and refuses to publish a gap; HTTP Range serving through `self.serveFromStorage()` on both engines, with conditional GET and a fail-closed content-type downgrade; the `s3` adapter completes the pluggable object-storage layer, storeless by design and able to offload GET/HEAD to a presigned URL; `getRange()` on every local strategy; machine-readable `err.code` on storage read verbs; and the Couchbase soak probes ship in the package · **Changed**: `renderStream()` is byte-serving-capable — `Buffer` chunks pass through verbatim on non-SSE content types (binary payloads previously arrived corrupted), HEAD answers headers-only without consuming the iterable, and caller-set headers are no longer clobbered · **Fixed**: `renderStream()` honours a caller-set status on both engines and stops throwing a swallowed error at the end of every streamed response, a redirect treats `HEAD` as the safe method it is and keeps the caller's query string under `keep-params: true`, and a local storage driver reclaims the temp files left behind by a crashed or refused `put()` |
 | **Q1 2027** | `0.6.x` | HTTP/2 priorities (blocked on Node scheduler hooks) · Beemaster admin + visual translation editor |
 | **2027** | `0.7.0` | Performance — remaining measure-gated candidates: multipart & WebSocket fast paths, render/log cleanups, SIMD scanner (the render-path deep-clone & id-mint reduction shipped early in `0.6.2` with a measured 4.4× render-throughput gain; the profiling baseline itself also shipped in `0.6.2`) |
 | **2027** | `0.8.0` | Financial-messaging foundations — XML request/response handling · pluggable message-schema validation · IBAN/BIC validation rules · money & ISO 4217 minor-unit utilities · idempotency keys · sequence primitive · OAuth2 client-credentials egress |
@@ -83,7 +84,7 @@ This roadmap covers planned features, architectural improvements, new connectors
 | ✅ | **Stale built-release watch** — For LOCAL production rehearsals. A bundle serving a built release under `local` scope + a non-dev env has no hot-reload, so after you edit source it silently keeps serving the stale build. Opt in via `server.releaseWatch` in `settings.json`: the bundle watches its SOURCE tree, compares fingerprints against the manifest release stamp, and surfaces staleness on `GET /_gina/release/status` and a live `GET /_gina/release/events` SSE stream (notify mode, the default) — or auto-rebuilds on change (opt-in `auto` mode). `POST /_gina/release/rebuild` rebuilds with an **idle-gated restart** that waits on in-flight HTTP requests and `gina.registerBusyProbe` application probes, so a restart never interrupts in-flight work. Hard-gated on `local` scope + a non-dev env — never active on a real cluster. | `0.5.18-alpha` | 2026-07-16 |
 | ✅ | **Popin eager preload** — Opt-in idle warming for AJAX popin content. Mark a trigger with `data-gina-dialog-preload="eager"` (case-insensitive) and the popin plugin fetches its content after `window` load, at browser idle — one trigger at a time, off the critical path — so opening feels instant with no second GET. Same safety gates as the hover/focus warm: the `"false"` opt-out and the disabled skip apply identically, and an eager warm and a hover warm coalesce into a single GET (whichever runs second is a no-op). The pass is skipped when the browser signals Save-Data. Default behavior is unchanged — hover/focus warm remains the default. | `0.5.21-alpha` | 2026-07-19 |
 | ✅ | **Upload progress + drag-and-drop** — Extend the `data-gina-form-upload-*` staged client layer with transfer progress and drop-target support. **Progress shipped** (`0.5.24-alpha.2`): the staging POST reports real upload progress (`xhr.upload.onprogress`) through the registered `uploadProgress.<id>` client event, a `data-gina-form-upload-on-progress` window callback, and a declarative indicator (`data-gina-form-upload-progress`, default `<fieldId>-progress`) with a fully managed lifecycle. **Drag-and-drop shipped** (`0.5.24-alpha.2`): an attribute-marked dropzone (`data-gina-form-upload-dropzone="<elementId>"`, explicit id, opt-in) accepting dropped files through the exact same staging pipeline as the native file input — group tagging, previews, hidden metadata fields, reset/delete and upload progress included — with `idle`/`over`/`dropped` CSS state hooks, file-drags-only reaction, and first-file truncation on single-file inputs. Opt-in attributes, zero new dependencies, no server-contract change. | `0.5.24-alpha.2` | 2026-07-22 |
-| 📋 | **Pluggable object storage** — Named drivers pairing an **adapter** (where the bytes live) with a **strategy** (how keys are laid out), behind one callback-shaped contract. Keys are opaque, so a later layout change never breaks stored references; writes publish atomically by temp-and-rename, so a reader never observes a partial object; and every object carries a metadata row written through a pluggable store seam — an embedded SQLite file by default, or a `connectors.json` entry when several processes share one root. A driver root that sits inside any web-served directory refuses the boot, since objects there would be publicly fetchable. Much of the layer has already shipped: the `local` adapter with the `sharded` and `cas` (content-addressed, deduplicating, refcounted) strategies, size tiering, the metadata seam, boot validation, the `gina.storage()` accessor, upload groups publishing straight to a driver, and the `storage:stats` / `storage:gc` / `storage:verify` maintenance CLI with its admin-gated `/_gina/storage/*` endpoints. This milestone completes the layer — the `stream` strategy with resumable large-media uploads, an `s3` adapter, and HTTP Range serving in both engines. | `0.8.x` | 2027 |
+| 📋 | **Pluggable object storage** — Named drivers pairing an **adapter** (where the bytes live) with a **strategy** (how keys are laid out), behind one callback-shaped contract. Keys are opaque, so a later layout change never breaks stored references; writes publish atomically by temp-and-rename, so a reader never observes a partial object; and every object carries a metadata row written through a pluggable store seam — an embedded SQLite file by default, or a `connectors.json` entry when several processes share one root. A driver root that sits inside any web-served directory refuses the boot, since objects there would be publicly fetchable. Much of the layer has already shipped: the `local` adapter with the `sharded` (dated), `cas` (content-addressed, deduplicating, refcounted) and `stream` (large sequential media, with resumable out-of-order segment uploads) strategies, size tiering, byte-range reads, the metadata seam and its Couchbase store, boot validation, the `gina.storage()` accessor, upload groups publishing straight to a driver, the `storage:stats` / `storage:gc` / `storage:verify` maintenance CLI with its admin-gated `/_gina/storage/*` endpoints, and HTTP Range serving on both engines (`serveFromStorage()` — 206/416/304, conditional GET, strong key ETags). The `s3` adapter — storeless (the provider owns each object's metadata), S3-compatible, its client a project-side dependency, with presigned-URL offload serving (307) — has shipped on the development branch, completing the layer; the milestone closes with the release that carries it. | `0.8.x` | 2027 |
 
 ---
 
@@ -504,7 +505,7 @@ Gina's built-in per-bundle inspector. Phases 1–2 ship as an embedded SPA at `/
 | ✅ | **Beginner — Notes API** — Your first REST API: scaffold a project, define 3 routes in `routing.json`, write synchronous controller actions, read `req.post` / `req.params`, return JSON with `renderJSON()`, handle errors with `throwError()`. In-memory store — no database needed. | ~15 min | `0.3.0` | 2026-04-01 |
 | ✅ | **Tutorial locale detection** — `LocaleSettings` React component detects the reader's locale and timezone via `navigator.language` + `Intl` APIs and pre-fills the `settings.json` scaffold example. Inserted after the scaffold step in both tutorials. Falls back to `en_US`. | — | `0.3.0` | 2026-04-06 |
 | ✅ | **Intermediate — Link Shortener** — SQLite ORM connector, async controller actions, `render()` + `renderJSON()` in same bundle, HTTP 302 redirect, route `requirements` guard. Includes downloadable project ZIP. | ~30 min | `0.3.0` | 2026-04-01 |
-| 📋 | **Advanced** — Full production project: authentication, scoped data isolation, async/await, HTTP/2, structured logging, Docker/K8s deployment. Starts from the intermediate tutorial's finished state. | ~60 min | `0.6.x` | Q4 2026 |
+| ✅ | **Advanced — Going to Production** — Full production project: authentication, per-user data isolation, deny-by-default authorization, sessions, HTTP/2, structured logging, Docker/K8s deployment with `gina-container`. Continues the intermediate tutorial's finished state (downloadable). | ~60 min | `0.6.8` | 2026-08-14 |
 
 ---
 

package/framework/v0.6.8/VERSION

@@ -0,0 +1 @@
+0.6.8

package/framework/{v0.6.7 → v0.6.8}/core/config.js

@@ -2051,6 +2051,16 @@ function Config(opt, contextResetNeeded) {
                     ignoreWebRoot: true,
                     path: wroot,
                     code: 302,
+                    // #B352 — this route's `path` is a CONSTANT (the configured webroot),
+                    // so without this flag the redirect discards the caller's query: a
+                    // bare-webroot hit (`/app?t=…`) landed on `/app/` with the parameter
+                    // gone, and the application saw an unexplained missing value rather
+                    // than a bad link. A path-normalisation redirect must be transparent
+                    // to request state, hence opted in here rather than left to consumers.
+                    // Note `webrootAutoredirect: false` does NOT avoid this — that flag
+                    // only drops the extra site-root (`/`) match added below; the
+                    // bare-webroot match comes from this route's base `url` and remains.
+                    'keep-params': true,
                     // #COMPLY10 — with `webrootAutoredirect` this route's url becomes
                     // `'/,'+ …`, i.e. it also matches the SITE ROOT, across
                     // GET/POST/PUT/DELETE/HEAD. Gating it would make `/` itself deny,