gina 0.5.25 → 0.5.26

package/CHANGELOG.md

@@ -6,6 +6,23 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html),
 and is generated by [Changie](https://github.com/miniscruff/changie).
 
 
+## 0.5.26 - 2026-07-25
+### Added
+* Bundles can now invert their authorization posture with `settings.json > auth.requireAuthByDefault: true`: every route requires an authenticated session unless its `routing.json` `param` block carries `"public": true`. It composes with the existing `requireAuth` / `roles` / `policy` keys rather than replacing them — an explicitly gated route behaves exactly as before, and `public` can never un-gate one. The mode is strictly opt-in and strictly boolean (a truthy string refuses to boot rather than leaving every route silently ungated), and it is keyed per bundle, so one bundle enabling it never changes the posture of a sibling in a merged-mode process. The injected routes the framework adds for you — the site root, the custom error page, `/_status` and the upload endpoints — ship `"public": true`, so enabling the mode does not take them offline. The boot refuses three configurations the mode would otherwise make dangerous: `"public": true` on a route that also declares an explicit gate key; a login route the mode would gate, which would bounce to itself in an infinite redirect; and a mode-gated route that also declares `cache`, because the render cache is read before authorization runs and its key carries no user identity. `gina bundle:openapi` reflects the mode, so the emitted specification never declares a newly gated route as unauthenticated. Enable it in a non-production environment first and read the boot line, which reports how many routes it just gated.
+* Production transport posture (#COMPLY9): a bundle resolving a cleartext scheme outside the local scope now warns at boot, naming the remediation. `server.requireHttps: true` refuses to boot the cleartext bundle instead — pre-listen, so the port is never reachable — and `server.allowInsecure: true` acknowledges that TLS terminates upstream (mesh, ingress, reverse proxy), turning the warn into one info line. Both strict booleans; a non-boolean or setting both refuses to boot.
+### Fixed
+* Couchbase N1QL: a client-side SDK timeout now classifies as transient instead of permanent, and keeps its error message. The connector replaced the driver error with one built from the query `cause` envelope whenever that envelope was present — but the SDK attaches it to every query error, so a client-side timeout (which carries no server text) became an empty-message `Error` and lost the typed timeout class name the transient/permanent classifier matches on. The raw driver error is now forwarded whenever the envelope has no message to surface, so `err.isTransient` reports true and `err.message` keeps the SDK text. Server-side only — restart to pick it up.
+* `gina bundle:mcp-start --transport=http` now reads `GINA_MCP_AUTH_TOKEN` through the framework environment reader instead of `process.env` directly. The CLI moves every `GINA_*` variable out of `process.env` into the framework environment during startup, so the resolver's direct read always came back empty and the token was silently never applied — a deployment that supplied the bearer token only through that variable ran with no authentication. The `--auth-token` flag and the `mcp.json > server > authToken` manifest field were not affected. If you set the token through the environment variable, restart the server and confirm the startup line now reports `bearer auth: enabled`.
+* Couchbase N1QL: a `.sql` `@options` annotation that silently did nothing now logs a warning naming the problem. Two shapes were affected: an annotation the parser cannot read (braces are required — write `@options { … }`), and a parsed annotation whose keys are all dropped because no `consistency` key is present (keys such as `adhoc` or `timeout` apply only alongside `consistency`). Query behaviour is unchanged — the warning lists the ignored keys and shows the exact form to write. Server-side only — restart to pick it up.
+* Corrected `lib/merge`'s documentation, which contradicted the shipped behaviour: the two-argument form preserves existing target keys on a conflict (`override` defaults to `false`, not `true` as documented), and the array example now shows the real result — a two-argument array merge combines elements (`merge([1,2],[3,4])` gives `[1,2,3,4]`), while replacing the target array requires `override=true`. Behaviour is unchanged; only the JSDoc (including its copy embedded in the browser bundle) was wrong.
+* The JSON schemas now describe the route-authorization vocabulary. `auth.requireAuthByDefault` was missing from the `settings.json` schema whose `auth` block forbids unknown keys, so an editor flagged a perfectly valid deny-by-default configuration as invalid; and `param.requireAuth`, `param.roles`, `param.policy` and `param.public` were undeclared in the `routing.json` schema, so they were accepted but offered no completion, no type checking and no description on hover. Runtime behaviour is unchanged — the schemas are editor tooling, never enforced at boot.
+### Security
+* The framework control-plane listeners now bind an explicit host that defaults to loopback. A new `bind_host` setting (env `GINA_BIND_HOST`, flag `gina framework:set --bind-host=`) governs where the command socket and the MQ listener accept connections; it is separate from `host_v4`, which remains the address clients connect to, so a workstation pointing `host_v4` at another machine still starts its own daemon normally. Exposing the control plane beyond the local host is now a deliberate opt-in, the same way a bundle uses `--http-host`. Existing installs inherit the loopback default; set `bind_host` if you relied on reaching these ports from another machine.
+* A command name arriving over the framework socket is now constrained to the shipped command namespace before it is resolved to a handler, so it can only ever resolve inside `lib/cmd/`. Unresolvable names are answered on the connection instead of ending the daemon process, which previously stopped serving every other client; a one-shot offline CLI run still exits non-zero. The MQ listener likewise skips a malformed frame rather than letting the parse failure drop the listener.
+* The MCP Streamable HTTP transport now refuses to start without a bearer token once an ambient protection has been removed — that is, when it is bound to a non-loopback address, or when the `Origin` allowlist has been disabled with `allowedOrigins: ["*"]`. Nothing binds in that case, so the port is never reachable unauthenticated. The default posture is unchanged: on a loopback bind with the built-in `Origin` allowlist a token stays optional, because the bind and the allowlist are the protection. A new `allowInsecure` option (CLI `--allow-insecure`, or `mcp.json > server > allowInsecure`, strict boolean) waives the requirement for deployments that restrict access upstream instead — a service mesh, a NetworkPolicy, or an authenticating reverse proxy such as oauth2-proxy or nginx `auth_request`. Bearer validation now hashes both the presented and the configured token before the constant-time comparison, so neither the comparison nor its timing depends on token length.
+* A route that declares both an authorization key (`param.requireAuth` / `param.roles` / `param.policy`) and `cache` now refuses to boot. The render cache is read before the authorization gate runs and its key carries no user identity, so the first authenticated response was replayed verbatim to every later unauthenticated caller. The boot refusal names the route and the remedy; as a second layer, the render delegates never store a body for a gated route even if the configuration bypassed the lint. `auth.requireAuthByDefault` already refused this pairing for mode-gated routes — it now covers explicitly gated ones too. ACTION REQUIRED: a bundle pairing an authorization key with `cache` will not start until you drop `cache` or open the route.
+* A `method: "ws"` route that declares `param.requireAuth`, `param.roles` or `param.policy` now refuses to boot. A WebSocket handshake is answered by the engine's extended-CONNECT handler and never reaches the authorization gate, so those keys could never be enforced — yet the route linted clean, started, and was counted in the "Registered N authorization-gated route(s)" boot line, actively confirming protection that did not exist. Authenticate inside the `wsHandler` instead: it receives the full request and can inspect headers and cookies before accepting the socket. Relatedly, `auth.requireAuthByDefault` no longer counts WebSocket routes among the routes it gates, and names them at boot instead, since the mode cannot reach them either. ACTION REQUIRED: a bundle declaring an authorization key on a ws route will not start until the key is removed.
+
 ## 0.5.25 - 2026-07-25
 ### Added
 * controller:add scaffolds a NAMESPACE controller inside a bundle and prints the paste-ready routing.json rules to wire it. It generates controllers/controller.<name>.js with one JSDoc'd action stub per --controls entry (or a single default action when --controls is omitted), auto-detecting the bundle flavor: a view bundle gets self.render() stubs plus one template per action at templates/html/<name>/<action>.html, while an API-only bundle gets self.renderJSON() stubs and no templates. --api / --views force the flavor. The routing rules are PRINTED for you to paste — routing.json is never edited — so restart the bundle after wiring them. Controller and action names are validated (a lowercase letter followed by letters, digits or underscores; `controller` is reserved), and an existing controller is refused rather than overwritten. Offline CLI command — no bundle rebuild.

package/README.md

@@ -59,21 +59,28 @@ 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.5.25
-
-- **Added — machine-caller authentication for app routes.** A request presenting `Authorization: Bearer <key>` matching a caller named in `settings.json > auth.machine.callers` now passes the route authorization gate without a session: it satisfies `param.requireAuth`, its configured roles match route `roles` exactly like a session user's, and route policies receive it as `{ name, roles, machine: true }`. A session still wins when both are present. Strictly opt-in and fail-closed — `auth.machine.enabled` defaults false and the boot lint refuses every malformed shape rather than silently running open. Keys accept `${secret:KEY}` placeholders and are compared in constant time against sha256 hashes computed at boot, so raw keys are not retained; a presented-but-invalid key gets a clean `401` with `WWW-Authenticate: Bearer` and never the login redirect. Audit records carry the caller name as the actor plus `machine: true`, and `self.hasRole()` answers the caller's roles. An optional `auth.machine.authenticator` hook verifies any other sync-checkable credential (a JWT signature, an HMAC header, an `x-api-key` scheme). Server-side — restart your bundles. (MS3)
-- **Added — cross-service request-id propagation.** The always-on request id is now forwarded as `x-request-id` on every outbound `self.query()` call — the file-download proxy path and both the HTTP/1 and HTTP/2 inter-bundle client paths — so one logical request stays correlatable as it fans out across bundles. A caller that sets `x-request-id` explicitly is never overwritten, and only the sanitised resolved id is forwarded (never a raw inbound header). The server also echoes `X-Request-Id` back on every response on both engines, so a caller, load balancer or APM can read the id off the wire. Server-side — restart your bundles. (MS1)
-- **Added — `GET /_gina/health/check` on the default (express) engine**, mirroring the isaac engine's existing liveness endpoint. It returns `200` with `{"status":"healthy","timestamp":<ISO>}` and is deliberately ungated — no admin allowlist, no dev gate — so container liveness probes reach it off-loopback. Previously only isaac served it, so express bundles had no ungated liveness target and had to switch engines just to satisfy a Docker or Kubernetes healthcheck. Server-side — restart your bundles. (MS2)
-- **Added — the authorization contract in `bundle:openapi`.** Gated routes (`param.requireAuth` / `param.roles` / `param.policy`) now emit a `401` response entry, plus a `403` when roles or a policy add authorization beyond authentication, and a bundle with machine-caller auth configured gains `components.securitySchemes.bearerAuth` (`http`/`bearer`) with a per-operation `security` requirement on gated routes. Role and policy names are never emitted into the spec, and an un-gated, un-configured bundle's spec is byte-unchanged. (MS4)
-- **Added — the `controller:` CLI group.** `controller:add` scaffolds a namespace controller with one JSDoc'd action stub per `--controls` entry, auto-detecting the bundle flavor (a view bundle gets `self.render()` stubs plus a template per action; an API bundle gets `self.renderJSON()` stubs), and prints the paste-ready `routing.json` rules rather than editing your routing. `controller:remove` (alias `controller:rm`) deletes one only after a reference-aware scan of `routing.json` and every `requireController()` call — because a routing rule naming a namespace with no controller file silently falls back to the default controller instead of erroring, a bare delete is unsafe, so it refuses and lists the blockers. `controller:rename` renames in place and rewrites the references it can do safely, reporting anything a static rewrite cannot resolve rather than guessing. All three support `--dry-run` and `--format=json`; remove and rename confirm interactively and support `--force`. Offline CLI — no bundle rebuild. (#R9)
-- **Added — transient-vs-permanent classification for datastore connector errors.** When a connector query fails, the error reaching your controller now carries `err.isTransient` (true when a retry after backoff can succeed — a datastore timeout, a dropped connection, a node warming up after a restart, rebalance or failover) and `err.transientReason`, a normalized token naming the condition (`socket:econnrefused`, `postgres:serialization-failure`, `mongo:transient-transaction`, `couchbase:timeout`, …). A controller can branch on it to render an honest "temporarily unavailable, please retry" instead of a generic 500 for a condition that clears itself in seconds — without hand-rolling a vendor-error classifier. It normalizes signals every driver already carries (socket errno, driver codes and class names, ANSI SQLSTATE classes, MongoDB error labels, Couchbase N1QL cause codes) across all six datastore connectors, and is deliberately conservative: an unrecognized error, or a genuinely permanent one such as a DNS misconfiguration or a duplicate key, classifies as permanent. Purely additive — it sets only those two fields and never throws. Server-side — restart your bundles. (#CE1)
-- **Added — `settings.swig.autoescape`** (boolean, default false) to opt in to HTML-escaping of Swig `{{ variable }}` output as an XSS defense, mirroring the existing `settings.nunjucks.autoescape`. Swig's escaping default is unchanged in this release — set the flag per bundle to enable it. A non-boolean value now refuses bundle startup, so the security toggle can never be silently mis-typed.
-- **Added — `server.proxy.requireForwardedHeaders`** (opt-in, declared in the published schema): when true, a request is classified as reverse-proxied only when it carries an `X-Forwarded-Host` header, disabling the port-less-Host heuristic so internal service-DNS calls can never rewrite the worker's proxy-host context. This is the deterministic option for deployments whose front proxy always sends `X-Forwarded-Host`, and the only mechanism that also protects renders with no request of their own (worker- or cron-driven rendering). Defaults to false — the historical heuristic is unchanged.
-- **Added — a `processing` state on the staged upload progress indicator.** `data-gina-upload-progress-state` is stamped `processing` the moment the browser finishes sending the bytes — the window during which the server post-processes the upload (rendering a preview, transcoding, scanning) before it responds. On a fast link the bytes finish in milliseconds while that window can run for seconds, during which the bar would otherwise sit frozen at a full `uploading` state; the new state advances the state attribute only, leaving the bar full so a styled bar can show a distinct processing affordance via CSS, and a native indeterminate bar keeps animating. Purely additive and i18n-neutral. Browser-bundled — re-bake your bundles. (#R8)
-- **Fixed — absolute URLs poisoned by port-less internal calls.** A request whose `Host` carries no port — a container health probe on an app route, a service-mesh hop, a sibling-bundle call addressed by service or DNS name — was classified as reverse-proxied and rewrote the worker's proxy-host context, so later renders' `getUrl` / `url` filter output and cross-bundle redirect and error-fallback targets could emit the internal host. The template filters (swig and nunjucks) and both URL builders now prefer the emitting request's own per-request classification on both engines, Express included; the worker-global remains the fallback for renders without a request. Server-side — restart your bundles. (#B152)
-- **Fixed — the Couchbase connector no longer hangs the request when an N1QL query fails at the socket level** — connection refused or reset, or a node still warming up after a restart or rebalance — with no query-error envelope. The three query error handlers read the vendor `cause` unconditionally, so on such a failure a swallowed `TypeError` left the query callback un-fired and the request never settled: no response, no error page. Each handler now forwards a usable error on both paths and always settles the query. Server-side — restart your bundles. (#B153)
-- **Fixed — a file input declaring only its staging upload action no longer emits a spurious warning-and-error pair** — nor writes a visible error into the form's error container — on every bind and re-bind. The delete action deliberately has no framework default because its endpoint is app-specific, so its absence is now a quiet debug at bind time; the requirement is still enforced when a delete is actually triggered. Declaring the delete action explicitly, the previous workaround, is no longer needed. Browser-bundled — re-bake your bundles.
-- **Fixed — a staged-upload reset or delete click that matches none of the rendered previews now logs a diagnostic warning instead of silently doing nothing.** Previously a zero-match removal skipped its whole cleanup path — the server-side temp-file delete request, the progress-indicator reset, and the removal callback — with no signal, so orphaned temp files could go unnoticed. A normal removal is unchanged. Browser-bundled — re-bake your bundles. (#B150)
+## What's in 0.5.26
+
+> **Three behaviour changes to check before upgrading.** Two can stop a bundle
+> that you have not otherwise touched: a route pairing an authorization key with
+> `cache` now refuses to boot, and so does a `method: "ws"` route declaring
+> `requireAuth` / `roles` / `policy`. The third only adds a boot line — a bundle
+> resolving a cleartext scheme outside the `local` scope now warns, and refuses
+> only if you opt in with `server.requireHttps`. See the
+> [migration guide](https://gina.io/docs/migration) for each.
+
+- **Added — deny-by-default authorization.** `settings.json > auth.requireAuthByDefault: true` inverts a bundle's posture: every route requires an authenticated session unless its `routing.json` `param` block carries `"public": true`. It composes with the existing `requireAuth` / `roles` / `policy` keys rather than replacing them — an explicitly gated route behaves exactly as before, and `public` can never un-gate one. The mode is strictly opt-in and strictly boolean (a truthy string refuses to boot rather than leaving every route silently ungated), and it is keyed per bundle, so one bundle enabling it never changes the posture of a sibling in a merged-mode process. The routes the framework injects for you — the site root, the custom error page, `/_status` and the upload endpoints — ship `"public": true`, so enabling the mode does not take them offline. The boot refuses three configurations the mode would otherwise make dangerous: `"public": true` on a route that also declares an explicit gate key; a login route the mode would gate, which would bounce to itself in an infinite redirect; and a mode-gated route that also declares `cache`, because the render cache is read before authorization runs and its key carries no user identity. `gina bundle:openapi` reflects the mode, so the emitted specification never declares a newly gated route as unauthenticated. Enable it in a non-production environment first and read the boot line, which reports how many routes it just gated. Server-side — restart your bundles. (#COMPLY10)
+- **Added — a boot-time production transport posture guard.** A bundle resolving a cleartext scheme outside the `local` scope now warns once at boot, naming the remediation. `server.requireHttps: true` refuses to boot the cleartext bundle instead — pre-listen, so the port is never reachable — and `server.allowInsecure: true` acknowledges that TLS terminates upstream (mesh, ingress, reverse proxy), turning the warn into one info line. Both are strict booleans; a non-boolean, or setting both, refuses to boot. Server-side — restart your bundles. (#COMPLY9)
+- **Fixed — Couchbase client-side query timeouts now classify as transient and keep their message.** The connector replaced the driver error with one built from the query `cause` envelope whenever that envelope was present — but the SDK attaches it to every query error, so a client-side timeout (which carries no server text) became an empty-message `Error` and lost the typed timeout class name the transient/permanent classifier matches on. The raw driver error is now forwarded whenever the envelope has no message to surface, so `err.isTransient` reports true and `err.message` keeps the SDK text. Server-side — restart your bundles.
+- **Fixed — `gina bundle:mcp-start --transport=http` now actually applies `GINA_MCP_AUTH_TOKEN`.** It is read through the framework environment reader instead of `process.env` directly: the CLI moves every `GINA_*` variable out of `process.env` into the framework environment during startup, so the resolver's direct read always came back empty and the token was silently never applied — a deployment that supplied the bearer token only through that variable ran with no authentication. The `--auth-token` flag and the `mcp.json > server > authToken` manifest field were not affected. If you set the token through the environment variable, restart the server and confirm the startup line now reports `bearer auth: enabled`.
+- **Fixed — a Couchbase `.sql` `@options` annotation that silently did nothing now warns.** Two shapes were affected: an annotation the parser cannot read (braces are required — write `@options { … }`), and a parsed annotation whose keys are all dropped because no `consistency` key is present (keys such as `adhoc` or `timeout` apply only alongside `consistency`). Query behaviour is unchanged — the warning lists the ignored keys and shows the exact form to write. Server-side — restart your bundles.
+- **Fixed — the JSON schemas now describe the route-authorization vocabulary.** `auth.requireAuthByDefault` was missing from the `settings.json` schema whose `auth` block forbids unknown keys, so an editor flagged a perfectly valid deny-by-default configuration as invalid; and `param.requireAuth`, `param.roles`, `param.policy` and `param.public` were undeclared in the `routing.json` schema, so they were accepted but offered no completion, no type checking and no description on hover. Runtime behaviour is unchanged — the schemas are editor tooling, never enforced at boot.
+- **Fixed — `lib/merge`'s documentation contradicted the shipped behaviour.** The two-argument form preserves existing target keys on a conflict (`override` defaults to `false`, not `true` as documented), and the array example now shows the real result — a two-argument array merge combines elements (`merge([1,2],[3,4])` gives `[1,2,3,4]`), while replacing the target array requires `override=true`. Behaviour is unchanged; only the JSDoc (including its copy embedded in the browser bundle) was wrong.
+- **Security — the framework control-plane listeners now bind an explicit host that defaults to loopback.** A new `bind_host` setting (env `GINA_BIND_HOST`, flag `gina framework:set --bind-host=`) governs where the command socket and the MQ listener accept connections; it is separate from `host_v4`, which remains the address clients connect to, so a workstation pointing `host_v4` at another machine still starts its own daemon normally. Exposing the control plane beyond the local host is now a deliberate opt-in, the same way a bundle uses `--http-host`. Existing installs inherit the loopback default; set `bind_host` if you relied on reaching these ports from another machine.
+- **Security — a command name arriving over the framework socket is constrained to the shipped command namespace** before it is resolved to a handler, so it can only ever resolve inside `lib/cmd/`. Unresolvable names are answered on the connection instead of ending the daemon process, which previously stopped serving every other client; a one-shot offline CLI run still exits non-zero. The MQ listener likewise skips a malformed frame rather than letting the parse failure drop the listener.
+- **Security — a route that declares both an authorization key and `cache` now refuses to boot.** The render cache is read before the authorization gate runs and its key carries no user identity, so the first authenticated response was replayed verbatim to every later unauthenticated caller. The boot refusal names the route and the remedy; as a second layer, the render delegates never store a body for a gated route even if the configuration bypassed the lint. `auth.requireAuthByDefault` already refused this pairing for mode-gated routes — it now covers explicitly gated ones too. **Action required:** a bundle pairing `param.requireAuth` / `param.roles` / `param.policy` with `cache` will not start until you drop `cache` or open the route. (#B158)
+- **Security — the MCP Streamable HTTP transport refuses to start without a bearer token once an ambient protection has been removed** — that is, when it is bound to a non-loopback address, or when the `Origin` allowlist has been disabled with `allowedOrigins: ["*"]`. Nothing binds in that case, so the port is never reachable unauthenticated. The default posture is unchanged: on a loopback bind with the built-in `Origin` allowlist a token stays optional, because the bind and the allowlist are the protection. A new `allowInsecure` option (CLI `--allow-insecure`, or `mcp.json > server > allowInsecure`, strict boolean) waives the requirement for deployments that restrict access upstream instead — a service mesh, a NetworkPolicy, or an authenticating reverse proxy. Bearer validation now hashes both the presented and the configured token before the constant-time comparison, so neither the comparison nor its timing depends on token length.
+- **Security — a `method: "ws"` route that declares `param.requireAuth`, `param.roles` or `param.policy` now refuses to boot.** A WebSocket handshake is answered by the engine's extended-CONNECT handler and never reaches the authorization gate, so those keys could never be enforced — yet the route linted clean, started, and was counted in the "Registered N authorization-gated route(s)" boot line, actively confirming protection that did not exist. Authenticate inside the `wsHandler` instead: it receives the full request and can inspect headers and cookies before accepting the socket. Relatedly, `auth.requireAuthByDefault` no longer counts WebSocket routes among the routes it gates, and names them at boot instead. **Action required:** a bundle declaring an authorization key on a ws route will not start until the key is removed. (#B159)
 
 See the full [Changelog](./CHANGELOG.md) and [Roadmap](./ROADMAP.md).
 

package/ROADMAP.md

@@ -50,6 +50,7 @@ This roadmap covers planned features, architectural improvements, new connectors
 | **Q3 2026** | `0.5.23` ✅ | **Fixed**: multipart `req.files[].size` now reports the exact stored byte count — the value was snapshotted before the write pipeline finished counting, coming up a varying whole-chunk short (file bytes on disk were always intact); it is finalized before the request resumes, so `self.store()` and any persister see the real size (#B142) · a multi-file multipart upload no longer hangs when an early small file finishes while a later large part is still streaming — the per-stream completion listeners now arm at creation (an already-finished stream's event never replays), and a mid-stream write error answers a guarded 500 instead of crashing the bundle; single-file uploads were unaffected (#B143) · the stale-release banner (`server.releaseWatch`) is now injected by the async template-loader render delegates too — a bundle on a custom async loader got the `/_gina/release/*` endpoints and SSE but no in-page banner; both async delegates (swig / nunjucks) now splice it onto the finalized HTML like the sync paths, CSP-nonce-aware, byte-inert outside the gate (#RWATCH) |
 | **Q3 2026** | `0.5.24` ✅ | **Added**: upload progress for the staged upload client layer — the staging POST reports real client-to-server wire progress via a new `uploadProgress.<id>` form event and an opt-in declarative `<progress>` / percent indicator (#R8, slice 1) · drag-and-drop — a file input binds a named element as a dropzone that routes dropped files through the exact same staging pipeline as the native picker, opt-in and explicit-id-only with `idle`/`over`/`dropped` CSS state hooks (#R8, slice 2) · an incident `ref` on every error response — a short voice-relayable correlation code (present in all scopes) that a server-side log line pairs with the full error detail before the wire copy is stripped, so support can resolve a user-relayed ref to the exact failure even in production (#ERRREF) · a per-upload-group `simulateWriteError` flag (non-production only) to verify the upload write-error crash-guard on your own surface after an upgrade (#B144) · **Fixed**: the staged upload client layer no longer corrupts binary uploads — the multipart body is now a Blob of raw file bytes instead of a UTF-8-inflating DOMString, so images / PDFs / archives are stored byte-identical (the defect only surfaced on gina ≥ 0.5.22; corrupted files are losslessly recoverable) (#B148) · a misconfigured upload group whose destination directory cannot be created answers a guarded 500 instead of crashing the bundle (#B145) · a file input declaring only its upload action is no longer silently repointed at the reset/delete route (#B146) · an upload no longer throws in its success handler when no preview element is present (#B147) |
 | **Q3 2026** | `0.5.25` ✅ | **Added**: microservices readiness — machine-caller authentication (an `Authorization: Bearer` key named in `settings.json > auth.machine.callers` satisfies route authorization without a session, opt-in and fail-closed, constant-time compared against boot-computed hashes, with an optional custom authenticator hook for JWT/HMAC/api-key schemes), cross-service request-id propagation (the always-on request id forwarded as `x-request-id` on every `self.query()` and echoed back on every response, so one logical request stays correlatable across bundles), an ungated `GET /_gina/health/check` on the express engine so container liveness probes no longer require the isaac engine, and the authorization contract in `bundle:openapi` (gated routes emit `401`/`403` entries and a `bearerAuth` security scheme, never role or policy names) · the `controller:` CLI group — `controller:add` scaffolds a namespace controller with per-action stubs and prints paste-ready routing rules, `controller:remove`/`rm` deletes only after a reference-aware scan that refuses while any routing rule or `requireController()` still points at it, and `controller:rename` rewrites the references it can resolve safely and reports the rest (#R9) · transient-vs-permanent classification for datastore connector errors — `err.isTransient` + a normalized `err.transientReason` on every connector query failure across all six datastore connectors, so an application can render an honest retry response without string-matching vendor error text; conservative by design, an unrecognized or genuinely permanent error classifies as permanent (#CE1) · `settings.swig.autoescape` to opt in to Swig output escaping (default unchanged; a non-boolean now refuses boot) · `server.proxy.requireForwardedHeaders` to require `X-Forwarded-Host` for proxy classification, the deterministic alternative to the port-less-Host heuristic · a `processing` state on the staged upload progress indicator, covering the server post-processing window so a full bar reads as working rather than stuck (#R8) · **Fixed**: absolute URLs poisoned by port-less internal calls — a health probe, service-mesh hop or service-DNS sibling call could rewrite the worker's proxy-host context and leak the internal host into later renders' `getUrl`/`url` output and cross-bundle redirect targets; emitting requests now prefer their own classification on both engines (#B152) · the Couchbase connector no longer hangs a request when an N1QL query fails at the socket level with no query-error envelope — the callback went un-fired and the request never settled (#B153) · a file input declaring only its staging upload action no longer emits a spurious warning-and-error pair on every bind · a staged-upload removal matching no preview now logs a diagnostic instead of silently skipping its whole cleanup path, including the temp-file delete (#B150) |
+| **Q3 2026** | `0.5.26` ✅ | **Security**: a route pairing an authorization key (`param.requireAuth` / `param.roles` / `param.policy`) with `cache` now refuses to boot — both render-cache serve points run BEFORE the authorization gate and the cache key carries no user identity, so the first authenticated response was replayed verbatim to every later anonymous caller; as a second layer the render delegates never store a body for a gated route even if the configuration bypassed the lint (#B158) · a `method: "ws"` route declaring an authorization key now refuses to boot — a WebSocket handshake is answered by the engine's extended-CONNECT handler and never reaches the gate, so those keys could never be enforced while the boot line still counted the route as protected; authenticate inside the `wsHandler`, which receives the full request (#B159) · the framework control-plane listeners now bind an explicit host defaulting to loopback — a new `bind_host` setting (env `GINA_BIND_HOST`, `gina framework:set --bind-host=`), separate from `host_v4`, so exposing the command socket and MQ listener beyond the local host is a deliberate opt-in · a command name arriving over the framework socket is constrained to the shipped `lib/cmd/` namespace before it resolves, and an unresolvable name is answered on the connection instead of ending the daemon for every other client · the MCP Streamable HTTP transport refuses to start without a bearer token once an ambient protection is removed (a non-loopback bind, or `allowedOrigins: ["*"]`), with a new `allowInsecure` waiver for deployments that restrict access upstream · **Added**: deny-by-default authorization — `settings.json > auth.requireAuthByDefault: true` requires an authenticated session on every route unless its `param` block carries `"public": true`; opt-in, strictly boolean, keyed per bundle so one bundle never changes a sibling's posture in merged mode, with the framework-injected routes shipping exempt and boot refusals for the login-route lockout, the `public`-plus-explicit-key contradiction, and a mode-gated route that also declares `cache`; `bundle:openapi` follows the mode (#COMPLY10) · a boot-time production transport posture guard — a cleartext scheme outside the `local` scope warns once at boot, `server.requireHttps` refuses to start instead (pre-listen, so the port is never reachable), and `server.allowInsecure` acknowledges that TLS terminates upstream (#COMPLY9) · **Fixed**: Couchbase client-side query timeouts classify as transient and keep their message — the connector rebuilt the error from the query `cause` envelope the SDK attaches to every query error, so a client-side timeout became an empty-message `Error` that had lost the typed class name the classifier matches on (#B153) · `gina bundle:mcp-start --transport=http` now actually applies `GINA_MCP_AUTH_TOKEN` — the resolver read `process.env` directly while the CLI had already moved every `GINA_*` variable into the framework environment, so a deployment supplying the token only that way ran with no authentication · a `.sql` `@options` annotation that silently did nothing now warns, naming the ignored keys and showing the working form (#B155) · the `settings.json` and `routing.json` schemas now describe the route-authorization vocabulary, so an editor no longer flags a valid deny-by-default configuration as invalid · `lib/merge`'s JSDoc no longer documents an inverted `override` default |
 | **Q4 2026** | `0.6.0` | Security & compliance controls (technical safeguards mapping to PCI-DSS / SOC2 / HIPAA) |
 | **Q1 2027** | `0.5.x` | HTTP/2 priorities (blocked on Node scheduler hooks) · Beemaster admin + visual translation editor |
 | **Q3 2027** | `1.0.0` | First stable release — Windows alpha compatibility is a hard gate |
@@ -270,9 +271,9 @@ Technical-safeguard primitives that map to the **PCI-DSS**, **SOC2**, and **HIPA
 | 📋 | **Application-level rate limiting** — Per-endpoint / per-client throttling at the route layer (today only an HTTP/2 rapid-reset limiter exists). Maps to PCI-DSS anti-automation and SOC2 availability. | `0.6.x` | Q4 2026 |
 | 📋 | **Data-at-rest / field-level encryption helpers** — Field-level encryption + key-management utilities. Maps to PCI-DSS req 3 and HIPAA §164.312(a)(2)(iv). | `0.6.x` | Q4 2026 |
 | 📋 | **Compliance control-mapping guide** — A reference mapping each Gina control to the PCI-DSS / SOC2 / HIPAA requirement it supports, plus an explicit "what the framework does not cover" section (to follow). | `0.6.x` | Q4 2026 |
-| 📋 | **Transport-security posture** — A production-scope HTTPS enforcement option (refuse or warn when a bundle serves plain HTTP outside local/dev scope), with a "TLS terminates upstream" escape hatch for the common mesh/ingress pattern, plus documented guidance for terminating mTLS at the mesh or ingress. Maps to the "encrypt everywhere / no implicit network trust" principle of NIST SP 800-207 (Zero Trust). | `0.6.x` | Q4 2026 |
-| 📋 | **Deny-by-default authorization mode** — An opt-in posture where every route requires authentication unless explicitly marked public, inverting today's per-route opt-in (a route that declares nothing is currently untouched). Complements the shipped Authorization / RBAC control. Maps to NIST SP 800-207 least-privilege / deny-by-default. | `0.6.x` | Q4 2026 |
-| 📋 | **Zero-Trust deployment guide** — A guide to running Gina inside a zero-trust architecture (NIST SP 800-207): terminating mTLS at the mesh/ingress, enforcing HTTPS, applying network default-deny between services, and shipping the built-in audit/metrics telemetry to a SOC. An honest-boundary companion to the compliance control-mapping guide — the framework supplies the enforcement point, identity, and telemetry; the deployment supplies transport identity and segmentation. | `0.6.x` | Q4 2026 |
+| ✅ | **Transport-security posture** — A bundle resolving a cleartext scheme outside the local scope warns once at boot, naming the bundle, scheme, and scope alongside both remediations. `server.requireHttps: true` refuses the boot instead — the throw lands pre-listen, so the cleartext port is never reachable at all. `server.allowInsecure: true` is the "TLS terminates upstream" acknowledgment for the mesh / ingress / reverse-proxy topology, turning the warning into a single info line; declaring both is a boot-refused contradiction. Both are strict booleans resolved exactly like `scheme` itself — the bundle's settings win and `env.json`'s `server` block fills — and a non-boolean value refuses the boot in every scope. Terminating mTLS stays a mesh/ingress concern by design. Maps to the "encrypt everywhere / no implicit network trust" principle of NIST SP 800-207 (Zero Trust). | `0.5.26-alpha.2` | shipped |
+| ✅ | **Deny-by-default authorization mode** — `settings.json > auth.requireAuthByDefault: true` inverts a bundle's posture: a route declaring no authorization key is gated rather than open, and opts back out with `param.public: true`. The mode is keyed per bundle, so one bundle's posture can never un-gate a sibling's in a merged process. The existing `requireAuth` / `roles` / `policy` keys are unaffected — only the un-annotated route changes — and `public` is evaluated inside the un-annotated branch, so a route carrying it alongside an explicit gate key stays gated even in a hand-edited config. The boot refuses the three shapes the mode makes dangerous: `public` beside an explicit gate key, a login route the mode would gate (an infinite self-bounce), and a mode-gated route that also declares `cache` (the render cache is read before authorization and its key carries no identity). The five framework-injected routes ship exempt, so enabling the mode cannot take the site root or the error renderer offline. Complements the shipped Authorization / RBAC control. Maps to NIST SP 800-207 least-privilege / deny-by-default. | `0.5.26-alpha.2` | shipped |
+| ✅ | **Zero-Trust deployment guide** — [Running Gina zero-trust](https://gina.io/docs/guides/zero-trust) walks the NIST SP 800-207 tenets against the controls Gina actually ships: deny-by-default authorization, the transport-posture knobs, terminating mTLS at the mesh or ingress, network default-deny between services, keeping the framework control sockets on loopback, and shipping the built-in audit / metrics / request-correlation telemetry to a SOC. An honest-boundary companion to the compliance control-mapping guide — the framework supplies the enforcement point, identity, and telemetry; the deployment supplies transport identity and segmentation. | `0.5.26-alpha.2` | shipped |
 
 ---
 

package/bin/cli

@@ -55,6 +55,7 @@ async function onExec() {
         , settings          = null
         , hostname          = os.hostname() // by default
         , hostV4            = null
+        , bindHost          = null
         , mqPort            = null
         , settingsPath      = null
         , err               = null
@@ -122,6 +123,13 @@ async function onExec() {
                     continue;
                 }
 
+                if ( isFrameworkScopedCmd && /^\-\-bind\-host/.test(params[p]) ) {
+                    let bind = params[p].split(/\=/)[1];
+                    setEnvVar('GINA_BIND_HOST', bind);// jshint ignore:line
+                    isUpdateRequired = true;
+                    continue;
+                }
+
                 if ( isFrameworkScopedCmd && /^\-\-hostname/.test(params[p]) ) {
                     hostname = params[p].split(/\=/)[1];
                     setEnvVar('GINA_HOSTNAME', hostname);// jshint ignore:line
@@ -185,6 +193,7 @@ async function onExec() {
         if (_hasUnresolved(settings['mq_port']))    { settings['mq_port']   = 8125; }
         if (_hasUnresolved(settings['port']))       { settings['port']      = 8124; }
         if (_hasUnresolved(settings['host_v4']))    { settings['host_v4']   = '127.0.0.1'; }
+        if (_hasUnresolved(settings['bind_host']))  { settings['bind_host'] = '127.0.0.1'; }
         if (_hasUnresolved(settings['hostname']))   { settings['hostname']  = undefined; }
 
         setEnvVar('GINA_LOG_LEVEL', settings['log_level']);// jshint ignore:line
@@ -238,6 +247,12 @@ async function onExec() {
         }
         hostV4 = getEnvVar('GINA_HOST_V4') || settings['host_v4'] || '127.0.0.1';// jshint ignore:line
         mqPort = getEnvVar('GINA_MQ_PORT')|| settings['mq_port'] || 8125;// jshint ignore:line
+        // Bind address for the framework control sockets (command socket + MQ
+        // listener). Deliberately independent of `host_v4`, which is the
+        // address CLIENTS connect to: a workstation may legitimately point
+        // `host_v4` at another machine, and inheriting that as a bind address
+        // would make the local daemon fail to start (EADDRNOTAVAIL).
+        bindHost = getEnvVar('GINA_BIND_HOST') || settings['bind_host'] || '127.0.0.1';// jshint ignore:line
 
         if (!isUpdateRequired) {
             setEnvVar('GINA_HOST_V4', settings['host_v4']);// jshint ignore:line
@@ -266,7 +281,10 @@ async function onExec() {
         if ( /(gina\/bin\/cli|gina\/\/bin\/gina)$/.test(process.argv[1]) ) {
 
             var MQListener = require(frameworkPath + '/lib/logger/src/containers/mq/listener.js');
-            var mqListener = await new MQListener({ port: mqPort, host: hostV4 });
+            // The listener reads `opt.hostV4` (see listener.js); passing `host`
+            // left it undefined, which binds every interface. Bind the control
+            // plane to `bind_host` (loopback by default) like the command socket.
+            var mqListener = await new MQListener({ port: mqPort, hostV4: bindHost });
             // required for tail command
             var mqPortFile = getTmpDir() + '/mq-listener-v'+ version +'.port';// jshint ignore:line
             console.debug('Writting: '+ mqPortFile);
@@ -323,6 +341,7 @@ async function onExec() {
 
         settings['mq_port'] = getEnvVar('GINA_MQ_PORT') || settings['mq_port'] || null;// jshint ignore:line
         settings['host_v4'] = getEnvVar('GINA_HOST_V4') || settings['host_v4'] || null;// jshint ignore:line
+        settings['bind_host'] = getEnvVar('GINA_BIND_HOST') || settings['bind_host'] || null;// jshint ignore:line
         settings['hostname'] = getEnvVar('GINA_HOSTNAME') || settings['hostname'] || null;// jshint ignore:line
         generator.createFileFromDataSync(settings, settingsPath);// jshint ignore:line
     }
@@ -391,6 +410,7 @@ async function onExec() {
                 homedir         : home,
                 port            : port,
                 hostV4          : hostV4,
+                bindHost        : bindHost,
                 mqPort          : mqPort,
                 hostname        : hostname,
                 debugPort       : debugPort,
@@ -418,6 +438,7 @@ async function onExec() {
             homedir         : home,
             port            : port,
             hostV4          : hostV4,
+            bindHost        : bindHost,
             mqPort          : mqPort,
             hostname        : hostname,
             debugPort       : debugPort,

package/bin/cmd

@@ -25,6 +25,10 @@ function Cmd(opt, runOffine) {
         local.hostV4            = opt.hostV4;
         local.mqPort            = opt.mqPort;
         local.port              = opt.port;
+        // Bind address for the framework command socket. Defaults to loopback
+        // here as well as at the resolution site (bin/cli), so a caller that
+        // omits the key can never widen the bind by accident.
+        local.bindHost          = opt.bindHost || '127.0.0.1';
 
         lib = require(local.frameworkPath + "/lib");
 
@@ -145,7 +149,13 @@ function Cmd(opt, runOffine) {
             }
         });
 
-        framework.listen(local.port, function() { //'listening' listener
+        // The command socket is a local control plane: a connection to it
+        // executes a framework CLI command. `listen(port, cb)` with no host
+        // argument binds every interface, so the bind host is passed
+        // explicitly and defaults to loopback (`bind_host` / GINA_BIND_HOST).
+        // Widening it is a deliberate opt-in, the same way a bundle's
+        // `--http-host` is.
+        framework.listen(local.port, local.bindHost, function() { //'listening' listener
 
             //First time launch.
             lib.cmd.load({

package/bin/gina-init

@@ -368,6 +368,7 @@ var settingsOut = {
     debug_port          : '9229',
     mq_port             : '8125',
     host_v4             : '127.0.0.1',
+    bind_host           : '127.0.0.1',
     hostname            : os.hostname(),
     user                : userInfo.username,
     uid                 : String(userInfo.uid),

package/framework/v0.5.26/VERSION

@@ -0,0 +1 @@
+0.5.26

package/framework/{v0.5.25 → v0.5.26}/core/asset/plugin/dist/vendor/gina/js/gina.js

@@ -2154,13 +2154,15 @@ define("requireLib", function(){});
  * Works in Node.js (CommonJS) and browser (AMD / GFF) contexts.
  *
  * - Objects are merged recursively.
- * - Arrays and primitives from `source` overwrite `target` (unless `override=false`).
- * - Pass `true` as the last argument to force overwrite of existing keys.
+ * - Missing keys are always filled from `source`; on a CONFLICTING key the
+ *   `target` value is preserved by default.
+ * - Pass `true` as the last argument (`override`) to make `source` win instead.
  *
  * @example
  * var merge = require('lib/merge');
  * var result = merge({ a: 1 }, { b: 2 }); // { a: 1, b: 2 }
- * merge({ a: 1 }, { a: 9 }, false); // { a: 1 }  — target wins when override=false
+ * merge({ a: 1 }, { a: 9 });       // { a: 1 }  — default: target wins on conflicts
+ * merge({ a: 1 }, { a: 9 }, true); // { a: 9 }  — override: source wins
  */
 
 /**
@@ -2186,13 +2188,15 @@ function Merge() {
      *
      * @param {object|Array} target    - Target (base) object or array
      * @param {object|Array} source    - Source object or array to merge into target
-     * @param {boolean}      [override=true] - When `false`, existing target keys are preserved
+     * @param {boolean}      [override=false] - Pass `true` to let `source` overwrite existing target keys; by default they are preserved
      * @returns {object|Array} Merged result (mutates and returns `target`)
      *
      * @example
      * merge({ a: 1 }, { b: 2 })          // { a: 1, b: 2 }
-     * merge({ a: 1 }, { a: 9 }, false)   // { a: 1 }
-     * merge([1, 2],   [3, 4])            // [3, 4]
+     * merge({ a: 1 }, { a: 9 })          // { a: 1 }  — default: target wins
+     * merge({ a: 1 }, { a: 9 }, true)    // { a: 9 }
+     * merge([1, 2],   [3, 4])            // [1, 2, 3, 4]
+     * merge([1, 2],   [3, 4], true)      // [3, 4]
      */
     var browse = function (_target, _source) {
 

package/framework/{v0.5.25 → v0.5.26}/core/config.js

@@ -1940,7 +1940,14 @@ function Config(opt, contextResetNeeded) {
             url: '/_status',
             method: 'GET',
             param: {
-                control: 'getBundleStatus'
+                control: 'getBundleStatus',
+                // #COMPLY10 — the framework-injected routes carry no authorization keys,
+                // so `auth.requireAuthByDefault` would gate every one of them and a
+                // bundle would lock itself out by flipping one settings key. Marking
+                // them public preserves today's behaviour when a bundle opts into the
+                // mode; a bundle that WANTS one of them gated declares its own route at
+                // the same url. This is a monitoring surface, so it stays reachable.
+                public: true
             },
             scopes: [ ''+ scope ]
         };
@@ -1955,7 +1962,12 @@ function Config(opt, contextResetNeeded) {
             param: {
                 control: 'renderCustomError',
                 // default data : will be fed on error
-                error: {}
+                error: {},
+                // #COMPLY10 — the error RENDERER. Gating it would mean an error is
+                // rendered through a route that itself denies, so a bundle under
+                // deny-by-default could not render its own error pages. Exempt
+                // unconditionally.
+                public: true
             },
             scopes: [ ''+ scope ]
         };
@@ -1975,7 +1987,13 @@ function Config(opt, contextResetNeeded) {
                     control: "redirect",
                     ignoreWebRoot: true,
                     path: wroot,
-                    code: 302
+                    code: 302,
+                    // #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,
+                    // so deny-by-default would take the app's entry point offline. A
+                    // redirect-control route does run the gate, so this is not theoretical.
+                    public: true
                 },
                 scopes: [ ''+ scope ],
                 bundle: bundle,
@@ -2002,7 +2020,11 @@ function Config(opt, contextResetNeeded) {
                     "method": "POST",
                     "param": {
                         "control": "uploadToTmp",
-                        "title": "Upload file"
+                        "title": "Upload file",
+                        // #COMPLY10 — preserves today's behaviour under the mode. A
+                        // deny-by-default bundle that wants uploads authenticated
+                        // declares its own POST route at this url.
+                        "public": true
                     },
                     "scopes": [ ""+ scope ]
                 }
@@ -2015,7 +2037,9 @@ function Config(opt, contextResetNeeded) {
                     "method": "POST",
                     "param": {
                         "control": "deleteFromTmp",
-                        "title": "Delete uploaded file"
+                        "title": "Delete uploaded file",
+                        // #COMPLY10 — see `upload-to-tmp-xml` above.
+                        "public": true
                     },
                     "scopes": [ ""+ scope ]
                 }

package/framework/{v0.5.25 → v0.5.26}/core/connectors/couchbase/index.js

@@ -408,6 +408,17 @@ function Couchbase(conn, infos) {
                 } catch (parseErr) {
                     console.warn('[CONNECTOR] @options parse error in .sql file: ' + parseErr.message);
                 }
+            } else if ( /\@options/.test(queryString) ) {
+                // #B155 — the file SAYS `@options` but the annotation regex above matched
+                // nothing, so the whole annotation is a silent no-op. The regex demands
+                // `@options { … }` (single space, braces) — the historical docs taught a
+                // brace-less `key=value` form, and a double space before the brace misses
+                // too. Warn with the exact expected shape. (A prose mention of `@options`
+                // inside a comment also lands here — accepted: a spurious warn is cheaper
+                // than a silently-dead annotation.)
+                console.warn('[CONNECTOR] found `@options` but could not parse a brace-delimited object — '
+                    + 'annotation ignored. Write it as: @options { consistency: "request_plus" }\n'
+                    + 'Found on: ' + queryString.substring(0, 80));
             }
             optionsArr = null;
 
@@ -711,6 +722,16 @@ function Couchbase(conn, infos) {
                             if (o == 'consistency') continue;
                             queryOptions[o] = options[o];
                         }
+                    } else if ( options && Object.keys(options).length ) {
+                        // #B155 — a parsed `@options` with no `consistency` key never reaches
+                        // the SDK: the passthrough above is gated on `consistency`, so every
+                        // other key is dropped. Warn instead of silently ignoring; the gate
+                        // itself stays (un-gating would make historically-inert options
+                        // suddenly live for every consumer). An empty `@options {}` drops
+                        // nothing and stays quiet.
+                        console.warn('[CONNECTOR] @options is missing a `consistency` key — ignoring: '
+                            + Object.keys(options).join(', ')
+                            + '. Add e.g. "consistency": "not_bounded" alongside them to apply.\nFound on: '+ queryStatement);
                     }
 
 
@@ -986,8 +1007,18 @@ function Couchbase(conn, infos) {
                                     // never fired and the request hung forever. Build a usable error
                                     // on BOTH paths (forwarding the raw error preserves its
                                     // code/errno for downstream classification) and always settle.
+                                    //
+                                    // #B153 residual — synthesize ONLY when there is envelope text to
+                                    // surface. The node binding marshals first_error_code /
+                                    // first_error_message onto EVERY query error, so a CLIENT-side SDK
+                                    // timeout arrives with a defined-but-EMPTY message; building
+                                    // `new Error('')` from it destroyed the typed class name
+                                    // (Un/AmbiguousTimeoutError) the classifier matches on, and a
+                                    // retryable timeout was reported permanent. Raw-forwarding is
+                                    // lossless here: the raw error keeps `.cause`, so even an
+                                    // empty-message server envelope still classifies off the code table.
                                     var error;
-                                    if ( err && err.cause && typeof(err.cause.first_error_message) != 'undefined' ) {
+                                    if ( err && err.cause && typeof(err.cause.first_error_message) != 'undefined' && err.cause.first_error_message !== '' ) {
                                         error = new Error(err.cause.first_error_message);
                                         error.stack = trigger +'\n'+ err.cause.http_body;
                                         error.cause = err.cause;
@@ -1037,8 +1068,18 @@ function Couchbase(conn, infos) {
                                     // never fired and the request hung forever. Build a usable error
                                     // on BOTH paths (forwarding the raw error preserves its
                                     // code/errno for downstream classification) and always settle.
+                                    //
+                                    // #B153 residual — synthesize ONLY when there is envelope text to
+                                    // surface. The node binding marshals first_error_code /
+                                    // first_error_message onto EVERY query error, so a CLIENT-side SDK
+                                    // timeout arrives with a defined-but-EMPTY message; building
+                                    // `new Error('')` from it destroyed the typed class name
+                                    // (Un/AmbiguousTimeoutError) the classifier matches on, and a
+                                    // retryable timeout was reported permanent. Raw-forwarding is
+                                    // lossless here: the raw error keeps `.cause`, so even an
+                                    // empty-message server envelope still classifies off the code table.
                                     var error;
-                                    if ( err && err.cause && typeof(err.cause.first_error_message) != 'undefined' ) {
+                                    if ( err && err.cause && typeof(err.cause.first_error_message) != 'undefined' && err.cause.first_error_message !== '' ) {
                                         error = new Error(err.cause.first_error_message);
                                         error.stack = trigger +'\n'+ err.cause.http_body;
                                         error.cause = err.cause;
@@ -1301,8 +1342,12 @@ function Couchbase(conn, infos) {
                         // err.cause.first_error_message on it threw a swallowed TypeError so
                         // self.emit never fired and the request hung. Emit a usable error on
                         // BOTH paths (the raw error preserves its code/errno).
+                        // #B153 residual — the empty-message clause: a CLIENT-side SDK timeout
+                        // carries a defined-but-EMPTY first_error_message, so synthesizing from it
+                        // destroyed the typed class name the classifier matches on. Synthesize only
+                        // when there is envelope text; raw-forwarding keeps `.cause` either way.
                         var error;
-                        if ( err && err.cause && typeof(err.cause.first_error_message) != 'undefined' ) {
+                        if ( err && err.cause && typeof(err.cause.first_error_message) != 'undefined' && err.cause.first_error_message !== '' ) {
                             error = new Error(err.cause.first_error_message);
                             error.stack = trigger +'\n'+ err.cause.http_body;
                             error.cause = err.cause;

package/framework/{v0.5.25 → v0.5.26}/core/controller/controller.render-json.js

@@ -47,6 +47,10 @@ async function writeCache(bundle, opt, jsonContent, req, res, cacheIsEnabled, th
         ! req.routing.cache
         ||
         ! /^true$/i.test(cacheIsEnabled)
+        ||
+        // #B158 — a gated route is never stored: the key carries no principal and
+        // both serve points run before the gate. Full rationale on isRouteGated.
+        lib.authzGate.isRouteGated(req)
     ) {
         return;
     }

package/framework/{v0.5.25 → v0.5.26}/core/controller/controller.render-nunjucks.js

@@ -880,6 +880,10 @@ async function writeCache(local, self, bundle, opt, htmlContent, req, res) {
         ! req.routing.cache
         ||
         String(self.serverInstance._cacheIsEnabled).toLowerCase() !== 'true'
+        ||
+        // #B158 — a gated route is never stored: the key carries no principal and
+        // both serve points run before the gate. Full rationale on isRouteGated.
+        libRef.authzGate.isRouteGated(req)
     ) {
         return;
     }

package/framework/{v0.5.25 → v0.5.26}/core/controller/controller.render-swig.js

@@ -49,6 +49,10 @@ async function writeCache(bundle, opt, htmlContent, req, res, cacheIsEnabled, th
         // replaced: /^true$/i.test() (#P6); flag threaded as a param — module scope
         // has no render()-scoped bindings (see the #INS10 note at the top of this file)
         String(cacheIsEnabled).toLowerCase() !== 'true'
+        ||
+        // #B158 — a gated route is never stored: the key carries no principal and
+        // both serve points run before the gate. Full rationale on isRouteGated.
+        lib.authzGate.isRouteGated(req)
     ) {
         return;
     }

package/framework/{v0.5.25 → v0.5.26}/core/server.isaac.js

@@ -339,6 +339,18 @@ function ServerEngineClass(options) {
             // it inherits the strip.
             if ( clean.param && typeof(clean.param) == 'object' ) {
                 const { requireAuth, roles, policy, ...cleanParam } = clean.param;
+                // #COMPLY10 — `public` is an authorization key too: under deny-by-default
+                // the set of public routes IS the authentication surface, so serving the
+                // markers hands an anonymous client a free recon map of what it can reach.
+                // Stripped with `delete` rather than by joining the destructuring above,
+                // for two independent reasons: `public` is a strict-mode RESERVED WORD, so
+                // the bare binding form is a SyntaxError (only a renamed binding compiles);
+                // and a separate statement leaves the destructuring line byte-identical to
+                // what the #COMPLY1 tests pin. The `#P21`/`#P22` note at the top of this
+                // loop moved AWAY from `delete` for V8 hidden-class reasons on hot paths —
+                // this loop runs once at boot over a bounded route table, so that rationale
+                // does not apply here.
+                delete cleanParam.public;
                 clean.param = cleanParam;
             }
             _routing[_routingKeys[ri]] = clean;