gina 0.5.26 → 0.6.0

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.0 - 2026-07-28
+### Added
+* The audit trail can now carry a tamper-evidence hash chain. Opt in with `audit.chain.enabled: true` and a signing key (`audit.chain.secret`, a literal or a `${secret:VAR}` placeholder, or the `GINA_AUDIT_SECRET` environment variable) and every record gains a `hash` that chains from its predecessor — `HMAC-SHA256(secret, previousHash + canonical(record))`. The new offline command `gina audit:verify <bundle> @<project>` walks the trail and reports either the intact totals or the first break with its line and reason, exiting non-zero when the chain is broken. This detects any post-hoc edit, deletion, insertion or reordering of the trail by someone who does not hold the signing key. It is deliberately NOT a defence against the process that writes the records: that process holds the key and could forge a whole chain, so for that stronger adversary stream the trail to write-once (WORM / Object-Lock) storage, as the compliance guide already describes. Two boundaries are stated rather than implied: truncation at the exact tail is invisible to the chain (read the record count), and an empty trail verifies trivially. A crash mid-write leaves a torn tail that the next boot acknowledges with a chained break record and a loud warning rather than a crash loop. The boot refuses the deployment shapes a single linear chain cannot hold — no signing key, a connector `store` backend (whose seam carries no ordering guarantee), or two bundles chaining into the same `audit.file` — so a chain that cannot be trusted never starts silently. Server-side only; enabling the chain needs a bundle restart.
+* `req.login(user, done)` now works for gina-native bundles and rotates the session id before binding the user — the session-fixation defense. Previously the framework's login shim only served Passport bundles; without Passport it threw `passport.initialize() middleware not in use`, so native bundles bound the user by hand with no rotation. The native branch now regenerates the session (destroying the pre-login record), binds the principal at `req.session.user`, stamps the absolute-timeout anchor, persists, and reports through the required callback; when the session provider exposes no `regenerate()` it binds without rotation and warns. Passport bundles are untouched — Passport's own `req.login` still wins, and the shim's Passport branch is byte-identical. Outstanding CSRF tokens survive the rotation: they are re-derived from the current session id on the next response.
+* Opt-in absolute session timeout — `session({ absoluteTimeout: <ms> })` on the Session plugin, or `settings.json > session.absoluteTimeout` as the deployment default with bundle code winning (`absoluteTimeout: false` disables it). An authenticated session older than the cap — measured from login, the anchor `req.login()` stamps at session-id rotation; manually-bound sessions are anchored one request later — is destroyed on its next request regardless of activity, and the request proceeds with a fresh anonymous session, exactly as a naturally-expired record behaves. Fail-closed: when the record cannot be destroyed the authentication is still dropped. This is the fixed-cap half of session-lifetime control; idle expiry already existed (the cookie maxAge and the store-record TTL both roll with activity) and composes with it. Anonymous sessions are never touched, preserving `saveUninitialized: false` semantics, and without the option the plugin returns express-session's middleware unchanged. Declared in the published settings.json schema.
+* `lib.authn` adds the password primitives that are dangerous to hand-roll. `hashPassword` mints a scrypt hash encoded as a self-describing PHC string (`$scrypt$ln=17,r=8,p=1$<salt>$<key>`), so the cost parameters travel with the hash and can be raised later without a flag day. `verifyPassword` compares in constant time and ALSO verifies existing `$argon2*$` and `$2a/2b/2y$` (bcrypt) hashes through your own project's `argon2` / `bcrypt` package, so a bundle arriving with credentials already hashed — including one that followed gina's own published interim guidance — keeps working; gina never mints those formats, so there is one mint path and one set of parameters to reason about. `needsRehash` reports which stored hashes are below current policy, and a successful login can upgrade them transparently — the one moment the plaintext is in hand. `dummyVerify` spends a matching amount of work on the account-not-found branch to close the user-enumeration oracle; always pass `{like: <a stored hash>}` so the cost is read from real data rather than drifting from it. `validatePasswordPolicy` checks length first per NIST SP 800-63B — a 12-character minimum with no mandatory character classes by default — with composition rules and a `deny` substring list available, and returns stable machine-readable error codes. Passwords are normalised to Unicode NFC on both sides, so a user who registers on one device and signs in from another is not locked out by an encoding difference. Gina still owns no user record, credential store or login route: these are helpers, not an identity provider.
+* `lib.authn.createLockout()` adds an account-lockout engine — the credential-stuffing brake. Call `check(key, cb)` before spending a KDF so a locked account never reaches one, `recordFailure(key, cb)` on a failed attempt and `recordSuccess(key, cb)` on a good one; `reset(key, cb)` lifts a lock administratively. Defaults follow PCI-DSS v4.0.1 §8.3.4 — lock after 10 consecutive failures, for 30 minutes. The key is yours to choose (a user id, an email, an `email:ip` pair) because gina does not own the user record; pass `normalizeKey` whenever it comes from user input, or case variants of the same address each get their own counter and multiply the threshold. State lives in memory by default, which is per-process — pass a shared `store` (the same callback-shaped `get` / `set` / `del` contract the job and audit seams already use) for multi-replica correctness. Operations on a key are serialized, so failures arriving concurrently cannot each read the same counter and lose the count. Crossing the threshold writes one `auth.lockout` audit record on the transition, not one per attempt. Lockout is per-ACCOUNT and counts credential failures; it is not request-rate limiting, which is per-CLIENT and is tracked separately on the roadmap — the two defend different axes and neither substitutes for the other.
+* `lib.authn` adds RFC 6238 TOTP helpers for a second factor, implemented against the RFC rather than taking a dependency. `generateTotpSecret()` mints a base32 secret, `otpauthURL({ secret, account, issuer })` builds the `otpauth://` URI every standard authenticator app scans as a QR code, `generateTotp(secret)` produces a code, and `verifyTotp(token, secret)` checks the current step plus one either side in constant time, returning `{ valid, counter }`. Replay defence is yours, and `counter` is what it needs: persist the accepted counter per user and refuse anything not strictly greater, or an observed code stays usable for its whole acceptance window — the RFC makes this the verifier's job and gina has no place to write it. Storing the secret is yours too; treat it as a credential and encrypt it at rest. A malformed code returns `{ valid: false }` rather than throwing, so an attacker learns nothing from the difference, while an unusable secret does throw — that is a configuration fault, not a login attempt. Recovery codes are deliberately not built: they are single-use random strings, so `hashPassword` plus your own table already expresses them.
+### Fixed
+* The `settings.json` schema now describes the `audit` block, so the audit trail configuration gets the same editor support as the rest of the file. All five keys — `enabled`, `file`, `store`, `actorKey` and `events.authz` — were undeclared, so an editor offered no completion, no type checking and no description on hover, and a mistyped key or a wrong type surfaced only as a boot refusal at the next restart. The declaration mirrors the boot lint rather than merely permitting the keys: `enabled` and `events.authz` are strictly boolean (a truthy string such as "true" would leave the trail silently off), `file` and `store` are non-empty strings and mutually exclusive, and unknown keys are rejected — so an editor now flags the same shapes the boot would refuse. Runtime behaviour is unchanged; the schemas are editor tooling, never enforced at boot.
+* Fixed the control-plane dial regression introduced by the 0.5.26 loopback bind default: CLI-side clients (the command socket, the MQ speaker and file log containers, and `gina tail`) dialled `host_v4` while the daemon binds `bind_host`, so any deployment whose `host_v4` is a non-loopback address of the same machine — the common containerized shape — could not reach its own daemon and `bundle:start` aborted before the HTTP server ever bound. Clients now resolve the dial host through a locality check: a `host_v4` naming one of the machine's own interfaces dials the bind address (loopback by default, or `bind_host` when it is a concrete non-wildcard address), while a genuinely remote `host_v4` is dialled unchanged. The bind side is untouched, and the connection-refused error now names the dial target and the `bind_host` knob.
+* Fixed `bind_host` persistence: a value written by `gina framework:set --bind-host=` was silently reverted to the loopback default by the very next CLI invocation (the settings regeneration had a disk-to-env read-back for every connection key except `bind_host`) and by every container bootstrap (`gina-init` rewrote settings.json with a hardcoded loopback value). The persisted value now survives both paths; `GINA_BIND_HOST` still takes precedence when set, and unresolved template placeholders are skipped rather than preserved.
+* Fixed the Couchbase session store's `touch()`: an internal idle-check compared an elapsed value in milliseconds against a TTL in seconds, so it fired roughly 1000x sooner than intended and left `lastModified` un-refreshed on most calls — even though every `touch()` extends the document's expiry regardless. The stamp now tracks each extension, which keeps the client-side session countdown measuring from the right origin. The SDK 4 store additionally writes `lastModified` as an ISO 8601 UTC string, matching the redis, sqlite, mongodb and scylladb session stores; it previously wrote a zone-less local-time value that the browser re-parsed in its own timezone, skewing the countdown by the offset between them.
+* Fixed session-record TTL resolution in the redis, sqlite, mongodb and scylladb session stores: an implicit one-day default made the cookie-`maxAge` fallback in `set()`/`touch()` unreachable, so the stored record's lifetime ignored the session cookie unless a `ttl` was configured explicitly — a 1-hour cookie left its record alive server-side for 24 hours, and a 7-day cookie was silently cut to 24 hours. When neither the store options nor the connectors.json `ttl` is set, the record TTL now follows the cookie's `maxAge` (one day only when the cookie has none), matching the Couchbase session stores. An explicitly configured `ttl` still wins over `maxAge`. Note this moves record lifetimes in BOTH directions relative to the old accidental 24-hour cap.
+* The `settings.json` schema now describes the `session` block, so the session plugin's configuration gets the same editor support as the rest of the file. The three consumed keys — `session.cookie.sameSite`, `session.cookie.httpOnly` and `session.cookie.secure` — were undeclared, so an editor offered no completion, no type checking and no hover description for a documented configuration surface. The declaration mirrors the plugin's own factory-time validation (`sameSite` one of lax/strict/none, `httpOnly` boolean, `secure` true, false or "auto") and rejects unread keys — putting `maxAge` or a store `ttl` under `settings.json > session` has never had any effect, and an editor now says so. Runtime behaviour is unchanged; the schemas are editor tooling, never enforced at boot.
+* Fixed the SQLite session store expiring the very session it was asked to refresh. `touch()` stamped `now + ttl` without first checking the resolved ttl, so as a session neared its expiry — express-session's `cookie.maxAge` is a decaying remainder, which truncates to zero in the final second and turns negative once expired — the store wrote an already-past expiry and ended the session early. It now performs no write and returns cleanly on a non-positive ttl, matching the Redis, MongoDB and ScyllaDB stores, which already guarded this. Sessions with a positive ttl are refreshed exactly as before.
+* Corrected the published `connectors.json` JSON-schema declarations for the session-store `ttl` and `prefix` keys. Both were labelled "Redis only" while `ttl` is in fact read by the Redis, SQLite, MongoDB and ScyllaDB stores and `prefix` by Redis and SQLite, so editors steered you away from keys that do work. The `ttl` entry also still advertised a default of 86400, which stopped being true when an unset ttl began deferring to the cookie's `maxAge`; that stale default is gone and both descriptions now name the stores that read them, plus the Couchbase stores which take these as constructor options instead.
+* The Couchbase session store now requires `options.db` — the already-open bucket the model layer creates from the `session` connector entry (`getModel('session').getConnection()`) — and fails fast with an actionable error when it is missing or not a bucket, instead of crashing at bundle init inside a dead self-connect path that called the SDK v2 `openBucket()` API, absent from the supported v3/v4 SDKs. The connection options that only fed that dead path (`host`, `hosts`, `username`, `password`, `bucket`, `cachefile`) were removed with it.
+* Server-side getRoute() no longer crashes when a proxied context is active while no proxy hostname is resolvable (worker global and envConf fallback both unset): the route degrades to its direct hostname (route.isProxyHost flips false so toUrl() cannot stringify an unset value into the emitted URL) and a once-per-process warning names the degraded state; the url template filters hold getRoute's own resolution so their per-request override can never force an unset value over it, and the non-proxied branch now requires a truthy worker global (its typeof gate admitted null).
+### Security
+* The gina-native `logout()` shim now destroys the persisted session record instead of only clearing `req.session.user`: previously the store record, the session id and every other session key survived to TTL after logout — a leaked or intercepted session id stayed valid server-side long after the user logged out. `logout()` calls the session's own `destroy()` when it exposes one (express-session), degrades gracefully when it does not, and accepts an optional callback — `req.logout(function(err) { ... })`. Review flows that relied on other session keys surviving logout: the whole record is gone afterwards. The session cookie stays the consumer's to expire (its name is not discoverable by the framework), and Passport bundles are unaffected — the shim never installs when Passport is initialized.
+
 ## 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.

package/README.md

@@ -27,12 +27,13 @@ MVC framework for Node.js and Bun with built-in HTTP/2, multi-bundle architectur
 | Template engine | [`@rhinostone/swig`](https://github.com/gina-io/swig) — maintained fork with CVE-2023-25345 patched; streaming SSE/chunked via `renderStream()`. Nunjucks supported as opt-in via `render.engine = "nunjucks"` or per-section `"ext": ".njk"` |
 | Forms & validation | One rule engine for client and server — live checks, cross-field rules, ARIA states, localised messages; the server enforces the same rules on submit |
 | 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 |
+| 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 |
 | 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` |
-| Route authorization | `requireAuth` / `roles` / `policy` per route, login bounce with `resumeRequest()`, `self.hasRole()` |
-| Audit trail | Opt-in append-only JSONL audit log (`self.audit()`), authorization denials auto-recorded, always-on request ids |
+| 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 |
+| Route authorization | `requireAuth` / `roles` / `policy` per route or deny-by-default, login bounce with `resumeRequest()`, `self.hasRole()` |
+| Audit trail | Opt-in append-only JSONL audit log (`self.audit()`), authorization denials auto-recorded, always-on request ids; opt-in HMAC hash chain verified offline by `gina audit:verify` |
 | CSRF protection | Signed double-submit token middleware + Origin/Referer pre-filter + hardened session cookie |
 | Security headers | CSP with per-response nonces, HSTS, COOP / COEP / CORP, Referrer-Policy and the X-* family — per-header plugins or one `SecurityHeaders` wrapper |
 | Secrets | `${secret:KEY}` placeholders in bundle config — fail-closed, env-backed; `secrets:scan` / `secrets:check` CLI |
@@ -59,28 +60,39 @@ 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.26
+## What's in 0.6.0
 
-> **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
+> **Two behaviour changes to check before upgrading.** Neither refuses a boot,
+> but both change how an untouched bundle behaves. Session records in the redis,
+> sqlite, mongodb and scylladb stores now follow the session cookie's `maxAge`
+> when no `ttl` is configured, instead of an implicit one-day cap — lifetimes
+> move in **both** directions, so set an explicit `ttl` if you relied on the old
+> 24-hour behaviour. And `req.logout()` now destroys the whole session record
+> rather than only clearing `req.session.user`, so review any flow that expected
+> other session keys to survive logout. 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)
+> **Action required — settings reset.** `0.6.0` is a shortVersion bump (`0.5` →
+> `0.6`), so on install the framework creates a fresh `~/.gina/0.6/settings.json`
+> from defaults — your `~/.gina/0.5/settings.json` customizations (log level,
+> port, culture, timezone, etc.) are **not** carried forward. Re-apply them with
+> `gina framework:set`, or copy the values across. Root-level state
+> (`~/.gina/main.json`, `projects.json`, `ports.json`, `gina.db`) is shared
+> across short versions and is unaffected.
+
+- **Added — a tamper-evidence hash chain for the audit trail.** Opt in with `audit.chain.enabled: true` and a signing key (`audit.chain.secret`, a literal or a `${secret:VAR}` placeholder, or `GINA_AUDIT_SECRET`) and every record gains a `hash` chaining from its predecessor — `HMAC-SHA256(secret, previousHash + canonical(record))`. The new offline `gina audit:verify <bundle> @<project>` walks the trail and reports either the intact totals or the first break with its line and reason, exiting non-zero when the chain is broken. This detects any post-hoc edit, deletion, insertion or reordering by someone who does not hold the signing key; it is deliberately *not* a defence against the process that writes the records, which holds the key — for that adversary, stream the trail to WORM / Object-Lock storage as the compliance guide describes. Two boundaries are stated rather than implied: truncation at the exact tail is invisible to the chain (read the record count), and an empty trail verifies trivially. The boot refuses the deployment shapes a single linear chain cannot hold — no signing key, a connector `store` backend, or two bundles chaining into the same `audit.file` — so a chain that cannot be trusted never starts silently. Server-side — restart your bundles. (#COMPLY2)
+- **Added — `lib.authn`, the authentication primitives that are dangerous to hand-roll.** `hashPassword` mints scrypt hashes as self-describing PHC strings (`$scrypt$ln=17,r=8,p=1$<salt>$<key>`), so the cost travels with the hash and can be raised later without a flag day. `verifyPassword` compares in constant time and *also* verifies existing `$argon2*$` and `$2a/2b/2y$` (bcrypt) hashes through your own project's package, so a bundle arriving with credentials already hashed keeps working; paired with `needsRehash`, a successful login upgrades them transparently and the store migrates itself with no password resets. `dummyVerify` spends matching work on the account-not-found branch to close the user-enumeration oracle — always pass `{like: <a stored hash>}` so the cost is read from real data. `validatePasswordPolicy` checks length first per NIST SP 800-63B (12 characters, no mandatory character classes by default). `createLockout()` adds the credential-stuffing brake, defaulting to PCI-DSS v4.0.1 §8.3.4 — 10 consecutive failures, 30 minutes — serialized per key so concurrent failures cannot lose the count, with one `auth.lockout` audit record on the transition. And `generateTotpSecret` / `otpauthURL` / `generateTotp` / `verifyTotp` implement RFC 6238 for a second factor; replay defence is yours, and the returned `counter` is what it needs. Gina still owns no user record, credential store or login route — these are helpers, not an identity provider. Server-side — restart your bundles. (#COMPLY3)
+- **Added — `req.login()` works for gina-native bundles and rotates the session id.** Previously the login shim only served Passport bundles; without Passport it threw, so native bundles bound the user by hand with no rotation at all. The native branch now regenerates the session — destroying the pre-login record, the session-fixation defence — binds the principal at `req.session.user`, stamps the absolute-timeout anchor, persists, and reports through the required callback; where the session provider exposes no `regenerate()` it binds without rotation and warns. Anything stored in the pre-login session is destroyed by the rotation: read it before the call and re-set it in the callback if it must survive. Outstanding CSRF tokens re-derive from the current session id on the next response, and Passport bundles are untouched. Server-side — restart your bundles. (#COMPLY4)
+- **Added — an opt-in absolute session timeout.** `session({ absoluteTimeout: <ms> })` on the Session plugin, or `settings.json > session.absoluteTimeout` as the deployment default with bundle code winning (`absoluteTimeout: false` disables it). An authenticated session older than the cap — measured from login, not from last activity — is destroyed on its next request and the request proceeds with a fresh anonymous session, exactly as a naturally-expired record behaves. Fail-closed: when the record cannot be destroyed the authentication is still dropped. This is the fixed-cap half of session-lifetime control; idle expiry already existed (the cookie `maxAge` and the store-record TTL both roll with activity) and composes with it. Anonymous sessions are never touched, preserving `saveUninitialized: false` semantics. Declared in the published settings.json schema. Server-side — restart your bundles. (#COMPLY4)
+- **Security — `req.logout()` destroys the persisted session record.** It previously only cleared `req.session.user`: the store record, the session id and every other session key survived to TTL, so a leaked or intercepted session id stayed valid server-side long after the user logged out. It now calls the session's own `destroy()` when one is exposed, degrades gracefully when it is not, and accepts an optional callback — `req.logout(function (err) { … })`. **Review flows that relied on other session keys surviving logout: the whole record is gone afterwards.** The session cookie stays yours to expire (its name is not discoverable by the framework), and Passport bundles are unaffected — the shim never installs when Passport is initialized.
+- **Fixed — co-located CLIs reach the control plane again.** 0.5.26's loopback bind default carried a dial-side regression: CLI-side clients (the command socket, the MQ speaker and file log containers, and `gina tail`) dialled `host_v4` while the daemon binds `bind_host`, so any deployment whose `host_v4` is a non-loopback address of the same machine — the common containerized shape — could not reach its own daemon, and `bundle:start` aborted before the HTTP server ever bound. Clients now resolve the dial host through a locality check: a `host_v4` naming one of the machine's own interfaces dials the bind address, while a genuinely remote `host_v4` is dialled unchanged. The bind side is untouched, so nothing is newly exposed, and the connection-refused error now names both the dial target and the `bind_host` knob. If you applied the `GINA_BIND_HOST=0.0.0.0` workaround purely to un-break co-located CLIs, you can drop it after upgrading. (#B160)
+- **Fixed — `gina framework:set --bind-host=` now persists.** The value was silently reverted to the loopback default by the very next CLI invocation — the settings regeneration had a disk-to-env read-back for every connection key except `bind_host` — and again by every container bootstrap, which rewrote settings.json with a hardcoded value. The persisted value now survives both paths; `GINA_BIND_HOST` still takes precedence when set. (#B161)
+- **Fixed — session records honour the cookie `maxAge`.** In the redis, sqlite, mongodb and scylladb stores an implicit one-day default made the cookie-`maxAge` fallback in `set()` / `touch()` unreachable, so a record's lifetime ignored the session cookie unless a `ttl` was configured explicitly — a 1-hour cookie left its record alive server-side for 24 hours, and a 7-day cookie was silently cut to 24 hours. When neither the store options nor the connectors.json entry sets a `ttl`, the record TTL now follows the cookie's `maxAge` (one day only when the cookie has none), matching the Couchbase stores. An explicitly configured `ttl` still wins. **Note this moves record lifetimes in both directions** relative to the old accidental 24-hour cap. (#B163)
+- **Fixed — the SQLite session store no longer expires the session it was asked to refresh.** `touch()` stamped `now + ttl` without first checking the resolved ttl — and express-session's `cookie.maxAge` is a decaying remainder, which truncates to zero in the final second and turns negative once expired — so a session near its expiry had an already-past expiry written to it and ended early. It now performs no write and returns cleanly on a non-positive ttl, matching the redis, mongodb and scylladb stores which already guarded this. (#B166)
+- **Fixed — the Couchbase session store's `lastModified` is refreshed and UTC.** An internal idle check compared an elapsed value in milliseconds against a TTL in seconds, so it fired roughly 1000× sooner than intended and left `lastModified` un-refreshed on most calls — even though every `touch()` extends the document's expiry regardless. The stamp now tracks each extension, keeping the client-side session countdown measuring from the right origin. The SDK 4 store additionally writes it as an ISO 8601 UTC string, matching the redis, sqlite, mongodb and scylladb stores; it previously wrote a zone-less local-time value that the browser re-parsed in its own timezone. (#B165)
+- **Fixed — the Couchbase session store requires its open bucket explicitly.** It now takes `options.db` — the already-open bucket the model layer creates from the `session` connector entry (`getModel('session').getConnection()`) — and fails fast with an actionable error when it is missing or is not a bucket, instead of crashing at bundle init inside a dead self-connect path that called the SDK v2 `openBucket()` API, absent from the supported v3 and v4 SDKs. The connection options that only fed that dead path (`host`, `hosts`, `username`, `password`, `bucket`, `cachefile`) were removed with it. No working deployment is affected — the path they fed could not succeed on a supported SDK. (#B167)
+- **Fixed — server-side `getRoute()` no longer crashes when no proxy hostname is resolvable.** With the worker-wide proxied latch set but both proxy-hostname sources unset — the boot-time global and the per-render `envConf` fallback, each of which the framework itself can legitimately leave empty — every `getRoute()` call threw a `TypeError`, taking down any render or readiness probe that resolved a route. The route now degrades to its direct hostname and `route.isProxyHost` flips false, so `toUrl()` cannot stringify an unset value into the emitted URL; a once-per-process warning names the degraded state. The `url` template filters hold `getRoute()`'s own resolution so their per-request override can never replace a usable value with an unset one. Server-side — restart your bundles. (#B168)
+- **Fixed — the JSON schemas now describe the `audit` and `session` blocks.** All five audit keys (`enabled`, `file`, `store`, `actorKey`, `events.authz`) and the three consumed session-cookie keys (`sameSite`, `httpOnly`, `secure`) were undeclared, so an editor offered no completion, no type checking and no description on hover, and a mistyped key surfaced only as a boot refusal at the next restart. Each declaration mirrors the corresponding boot lint or factory-time validation rather than merely permitting the keys, and rejects unread keys — putting `maxAge` or a store `ttl` under `settings.json > session` has never had any effect, and an editor now says so. Separately, the `connectors.json` schema no longer labels the session-store `ttl` and `prefix` keys "Redis only" — `ttl` is read by the redis, sqlite, mongodb and scylladb stores and `prefix` by redis and sqlite — and its stale `86400` default is gone. Runtime behaviour is unchanged; the schemas are editor tooling, never enforced at boot.
 
 See the full [Changelog](./CHANGELOG.md) and [Roadmap](./ROADMAP.md).
 

package/ROADMAP.md

@@ -1,6 +1,6 @@
 # Gina — Roadmap
 
-This roadmap covers planned features, architectural improvements, new connectors, and AI integration. Items marked ✅ are shipped. All planned items are open to community contribution — see [CONTRIBUTING.md](./CONTRIBUTING.md) for how to get involved.
+This roadmap covers planned features, architectural improvements, new connectors, and AI integration. Items marked ✅ are shipped; **⏸ marks work that is scoped and measured but deliberately deferred** — it gets built when someone asks for it, and every deferred row names an interim pattern to use in the meantime. All planned items are open to community contribution — see [CONTRIBUTING.md](./CONTRIBUTING.md) for how to get involved.
 
 > **Docs:** [gina.io/docs](https://gina.io/docs/) · **Issues:** [github.com/gina-io/gina/issues](https://github.com/gina-io/gina/issues)
 
@@ -51,8 +51,11 @@ This roadmap covers planned features, architectural improvements, new connectors
 | **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 |
+| **Q4 2026** | `0.6.0` ✅ | **Security**: `req.logout()` now destroys the persisted session record instead of only clearing `req.session.user` — the store record, the session id and every other session key previously survived to TTL, so a leaked or intercepted session id stayed valid server-side long after the user logged out; it now accepts an optional callback, and Passport bundles are unaffected · **Added**: an opt-in tamper-evidence hash chain for the audit trail — `audit.chain` plus a signing key gives every record an HMAC that chains from its predecessor, and the new offline `gina audit:verify <bundle> @<project>` walks the trail and reports either the intact totals or the first break, so any post-hoc edit, deletion, insertion or reordering by someone who does not hold the key is detectable; the boot refuses the deployment shapes a single linear chain cannot hold rather than starting a chain that cannot be trusted (#COMPLY2) · `lib.authn` — the authentication primitives that are dangerous to hand-roll: scrypt password hashing encoded as self-describing PHC strings so the cost can be raised without a flag day, with argon2 and bcrypt verify-only routing through the project's own package so a store arriving with existing credentials keeps working and migrates itself on the next successful login, a `dummyVerify` that closes the user-enumeration oracle, NIST SP 800-63B password policy, a PCI-DSS v4.0.1 §8.3.4 account-lockout engine, and RFC 6238 TOTP; gina still owns no user record, credential store or login route (#COMPLY3) · `req.login(user, done)` now works for gina-native bundles and rotates the session id before binding the user — the session-fixation defence; it previously threw without Passport, so native bundles bound the user by hand with no rotation at all (#COMPLY4) · an opt-in absolute session timeout — `session({ absoluteTimeout })` or `settings.json > session.absoluteTimeout` — caps an authenticated session's total lifetime measured from login regardless of activity, composing with the idle expiry that already existed (#COMPLY4) · **Fixed**: co-located CLIs reach the control plane again — 0.5.26's loopback bind default left CLI-side clients dialling `host_v4` while the daemon binds `bind_host`, so any deployment whose `host_v4` is a non-loopback address of the same machine could not reach its own daemon and `bundle:start` aborted before the HTTP server ever bound (#B160) · `gina framework:set --bind-host=` now persists across the settings regeneration that runs on every command and across container bootstraps (#B161) · session records in the redis, sqlite, mongodb and scylladb stores now honour the cookie `maxAge` when no `ttl` is configured, instead of an implicit one-day default that made the fallback unreachable — record lifetimes move in both directions relative to the old 24-hour cap (#B163) · the SQLite store no longer expires the very session it was asked to refresh, guarding a non-positive resolved ttl as its siblings already did (#B166) · the Couchbase store's `touch()` re-stamps `lastModified` on every extension — an internal idle check compared milliseconds against seconds — and the SDK 4 store writes it as an ISO 8601 UTC string, matching the other stores (#B165) · the Couchbase session store now requires the already-open bucket as `options.db` and fails fast with an actionable error instead of crashing at bundle init inside a dead SDK v2 self-connect path (#B167) · server-side `getRoute()` no longer crashes when a proxied context is active while no proxy hostname is resolvable — the route degrades to its direct hostname instead of throwing, so a render or readiness probe that resolves a route survives the state (#B168) · the `settings.json` schema now describes the `audit` and `session` blocks, and the `connectors.json` schema no longer labels the session-store `ttl` and `prefix` keys "Redis only" nor advertises a stale 86400 default — editor tooling only, runtime behaviour unchanged |
+| **Q1 2027** | `0.6.x` | HTTP/2 priorities (blocked on Node scheduler hooks) · Beemaster admin + visual translation editor |
+| **2027** | `0.7.0` | Performance — runtime CPU profiling baseline · multipart & WebSocket hot-path acceleration · render/log hot-path cleanups (SIMD scanner deferred, measure-gated) |
+| **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 |
+| **2027** | `0.9.0` | Financial-integration heavyweights — entity-layer datastore transaction seam · message-queue connector family (AMQP / Kafka / IBM MQ) |
 | **Q3 2027** | `1.0.0` | First stable release — Windows alpha compatibility is a hard gate |
 
 ---
@@ -110,7 +113,7 @@ Stub commands confirmed in source — handler files exist but are empty or comme
 | ✅ | **`protocol:remove`** — Revert a bundle to the project's default protocol/scheme by removing its `settings.json` override (no shared `ports*.json` mutation), with `--dry-run` / `--force`. | `0.4.1-alpha.2` | 2026-05-31 |
 | ✅ | **`minion:list`** — List the running bundle child-processes ("minions") of a project, or of every project, grouped by project. `--format=json` supported. | `0.4.1-alpha.2` | 2026-05-31 |
 | ✅ | **`minion:kill`** — Reap a project's running bundle child-processes ("minions") — both pidfile-tracked and `ps`-discovered orphans — with a graceful SIGTERM/SIGKILL escalation and a `--dry-run` preview. | `0.4.1-alpha.2` | 2026-05-31 |
-| 📋 | **`gina --status` / `-t`** — Top-level health check: print whether the framework daemon is running, its version, and active bundle count. Requires adding `--status`/`-t` entries to `aliases.json` and implementing `framework/status.js`. | `0.5.x` | Q4 2026 |
+| 📋 | **`gina --status` / `-t`** — Top-level health check: print whether the framework daemon is running, its version, and active bundle count. Requires adding `--status`/`-t` entries to `aliases.json` and implementing `framework/status.js`. | `0.6.x` | Q4 2026 |
 | ✅ | **`bundle:copy` / `bundle:cp`** — Duplicate a bundle (source files + config) under a new name within the same project, with a word-boundary name rewrite, a fresh full protocol/scheme/env port matrix, and `--dry-run` / `--force`. | `0.4.1-alpha.2` | 2026-05-31 |
 | ✅ | **`project:status`** — Show the running/stopped state of each bundle in a project with PID and port info. | `0.4.1-alpha.2` | 2026-05-30 |
 
@@ -166,7 +169,7 @@ Stub commands confirmed in source — handler files exist but are empty or comme
 | ✅ | **Explicit exports for global helpers** — `getContext`, `setContext`, `_`, `requireJSON` etc. available as explicit `require('gina/gna').getContext` imports alongside the existing global injection. Enables IDE navigation and static analysis. | `0.3.3-alpha.3` | 2026-04-09 |
 | ✅ | **TypeScript declaration files** — `.d.ts` declarations for the public surface: `SuperController`, `EntitySuper`, connector config shapes, `routing.json` schema, `PathObject`, `uuid`, all config file interfaces, `GinaRequest`/`GinaResponse`. No TS migration of internals — just declarations for consumer projects. `package.json` wired with `"types"` and `"typesVersions"`. | `0.3.3-alpha.3` | 2026-04-09 |
 | ✅ | **Auto-generated `types/gna.d.ts` from JSDoc** (#M9) — `script/generate_gna_types.js` reads the `GLOBAL_EXPORTS` inventory from the gna-exports unit test plus the JSDoc on `framework/v*/core/gna.js` and emits `types/gna.d.ts` with one entry per global export. Two npm scripts: `npm run types:gen` regenerates, `npm run types:check` exits non-zero if drifted. A `gna-types-drift.test.js` unit test re-runs the generator in memory on every test pass — the JSDoc on `core/gna.js` is the single source of truth. Closes the #M8 → #M9 loop and removes the hand-written declaration. | `0.3.7-alpha.2` | 2026-04-18 |
-| 📋 | **`gina connector:audit [@project]`** — reads `connectors.json`, maps each declared connector to its npm peer package (`mysql2`, `pg`, `ioredis`, `couchbase`, `openai`, `@anthropic-ai/sdk`, etc.), and runs `npm audit --json` scoped to those packages in the project's `node_modules`. Reports CVEs with severity and fix availability. If `socket` is installed in the project, delegates to it for supply-chain analysis (malware, typosquatting, protestware) instead of `npm audit`. Exit code 1 on any high/critical finding — CI-friendly. Only audits packages actually declared in `connectors.json`, not the full dependency tree. | `0.5.x` | Q4 2026 |
+| 📋 | **`gina connector:audit [@project]`** — reads `connectors.json`, maps each declared connector to its npm peer package (`mysql2`, `pg`, `ioredis`, `couchbase`, `openai`, `@anthropic-ai/sdk`, etc.), and runs `npm audit --json` scoped to those packages in the project's `node_modules`. Reports CVEs with severity and fix availability. If `socket` is installed in the project, delegates to it for supply-chain analysis (malware, typosquatting, protestware) instead of `npm audit`. Exit code 1 on any high/critical finding — CI-friendly. Only audits packages actually declared in `connectors.json`, not the full dependency tree. | `0.6.x` | Q4 2026 |
 
 ### Phase 5 — Future
 
@@ -264,19 +267,38 @@ Technical-safeguard primitives that map to the **PCI-DSS**, **SOC2**, and **HIPA
 | Status | Feature | Version | Target |
 | --- | --- | --- | --- |
 | ✅ | **Authorization / RBAC** — Per-route authorization declared in `routing.json`: `param.requireAuth` requires an authenticated session, `param.roles: ["admin","editor"]` requires any one of a set of roles, and `param.policy: "ownsInvoice"` delegates to a per-bundle function for the record/attribute checks roles cannot express (evaluation order: authentication → roles → policy). Unauthenticated callers get a 401, or a non-cacheable login bounce when `settings.json > auth.loginRoute` is set (the paused request replays after sign-in); authorized-but-denied callers get a 403 whose body stays generic — the required roles and the policy name are never echoed to the wire. `self.hasRole(role)` covers actions that authorize mid-logic. A route that declares nothing is untouched, and any declaration that would leave a route silently ungated refuses to boot. Maps to PCI-DSS req 7, HIPAA §164.312(a)(1), SOC2 CC6 (least privilege). | `0.5.19-alpha.2` | shipped |
-| 📋 | **Tamper-evident audit trail** — A user-attributed, append-only, integrity-protected record of who did what to which record when, distinct from application logging. **The audit trail itself has already shipped** — `settings.json > audit.enabled` plus `self.audit(action, data)` writes an append-only JSONL trail (actor, action, resource, request id, ip, route, timestamp), and route-authorization denials are recorded automatically; see the changelog for the release that carries it. **What remains for this row is the tamper-evidence** — the HMAC hash chain that makes an edited, deleted, or reordered record detectable, plus `gina audit:verify`. Maps to PCI-DSS req 10, HIPAA §164.312(b), SOC2 CC7. | `0.6.x` | Q4 2026 |
-| 📋 | **Authentication hardening** — Password hashing/policy helpers, account lockout, and MFA/TOTP hooks. Maps to PCI-DSS req 8, HIPAA §164.312(d). | `0.6.x` | Q4 2026 |
-| 📋 | **Session lifecycle hardening** — Session-id rotation on privilege change and idle/absolute timeouts, on top of the existing Session plugin. Maps to PCI-DSS req 8.2. | `0.6.x` | Q4 2026 |
-| 📋 | **PII/PHI protection** — Production log-field redaction, data classification, and retention helpers (today's redaction is a dev-only inspector tool). Maps to HIPAA and SOC2 Privacy. | `0.6.x` | Q4 2026 |
-| 📋 | **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 |
+| ✅ | **Tamper-evident audit trail** — A user-attributed, append-only, integrity-protected record of who did what to which record when, distinct from application logging. The audit trail (`settings.json > audit.enabled` + `self.audit(action, data)` writing an append-only JSONL record — actor, action, resource, request id, ip, route, timestamp — with route-authorization denials recorded automatically) shipped first; the **tamper-evidence** now ships too: an opt-in HMAC hash chain (`audit.chain`) makes any edited, deleted, inserted, or reordered record detectable, verified offline with `gina audit:verify`. Detects tampering by anyone without the signing key (as change-detection it maps to PCI-DSS v4.0.1 §10.3.4); for the process that holds the key, stream the trail to a WORM/Object-Lock store (§10.3.2/§10.3.3). Maps to PCI-DSS req 10, HIPAA §164.312(b), SOC2 CC7. | `0.6.0` | shipped |
+| ✅ | **Authentication hardening** — `lib.authn` supplies the primitives that are dangerous to hand-roll, without becoming an identity provider: Gina still owns no user record, credential store, or login route, and the module ends where `req.login()` begins. `hashPassword` mints scrypt hashes encoded as self-describing PHC strings, so the cost parameters travel with the hash and can be raised later without a flag day — `needsRehash` reports which stored hashes are below policy and the next successful login upgrades them transparently, the one moment the plaintext is in hand. `verifyPassword` compares in constant time and also verifies existing argon2 and bcrypt hashes through your own project's package, so a bundle arriving with credentials already hashed keeps working; `dummyVerify` spends matching work on the account-not-found branch to close the user-enumeration oracle; `validatePasswordPolicy` checks length first per NIST SP 800-63B, with composition rules and a deny-list available. `createLockout()` adds the credential-stuffing brake — PCI-DSS §8.3.4 defaults of 10 consecutive failures and a 30-minute lock, a caller-chosen key with optional normalisation, per-key serialization so failures arriving concurrently cannot lose the count, a pluggable shared store for multi-replica correctness, and one `auth.lockout` audit record on the transition into locked; it is per-account credential lockout, not per-client request-rate limiting, which remains a separate roadmap item. RFC 6238 TOTP completes the set: secret generation, the `otpauth://` enrolment URI every standard authenticator scans, and constant-time verification returning the matched step as an absolute `counter` so your application can enforce replay defence. Maps to PCI-DSS req 8 (8.3.2 authentication-factor storage, 8.3.4 lockout, 8.4 MFA), HIPAA §164.312(d). | `0.6.0` | shipped |
+| ✅ | **Session lifecycle hardening** — `req.login(user, done)` now works without Passport and rotates the session id BEFORE binding the user (the session-fixation defense): the pre-login record is destroyed, the principal lands at `req.session.user`, and the absolute-timeout anchor is stamped — with a graceful bind-and-warn when the session provider exposes no `regenerate()`, and Passport bundles untouched. The Session plugin gained an opt-in absolute session cap: `session({ absoluteTimeout: <ms> })` or `settings.json > session.absoluteTimeout` (bundle code wins, `false` disables) destroys an authenticated session older than the cap on its next request — regardless of activity — and the request proceeds anonymously, exactly like a naturally-expired record; fail-closed when the record cannot be destroyed, anonymous sessions never touched so `saveUninitialized: false` keeps its meaning. Composes with the existing idle expiry (cookie `maxAge` + store-record TTL, both rolling with activity). Declared in the published settings.json schema. Maps to PCI-DSS req 8.2. | `0.6.0` | shipped |
+| ⏸ | **PII/PHI protection** — Production log-field redaction, data classification, and retention helpers (today's redaction is a dev-only inspector tool). **Deferred — built on request.** *Interim:* keep credentials and identifiers out of query strings, since the always-on access log records full request URLs. Maps to HIPAA and SOC2 Privacy. | — | on demand |
+| ⏸ | **Application-level rate limiting** — Per-endpoint / per-client throttling at the route layer (today only an HTTP/2 rapid-reset limiter exists). **Deferred — built on request.** *Interim:* throttle at your reverse proxy or ingress. Distinct from `lib.authn` account lockout, which brakes credential failures per account, not requests per client. Maps to PCI-DSS anti-automation and SOC2 availability. | — | on demand |
+| ⏸ | **Data-at-rest / field-level encryption helpers** — Field-level encryption + key-management utilities. **Deferred — built on request.** *Interim:* encrypt at the application layer with your platform's KMS SDK; `${secret:KEY}` delivers the key material. Maps to PCI-DSS req 3 and HIPAA §164.312(a)(2)(iv). | — | on demand |
+| ✅ | **Compliance control-mapping guide** — [Compliance control mapping](https://gina.io/docs/guides/compliance) maps every control Gina ships to the PCI-DSS v4.0.1, SOC 2 (2017 TSC), and HIPAA §164.312 requirement it supports, and states plainly where a framework's responsibility ends. Controls still on the roadmap are listed separately as unavailable, each with the interim pattern to use until it ships, so a planned control can never be mistaken for one you have. An explicit "what Gina does not — and cannot — cover" section names what no framework provides: the certification itself, legal instruments, network and physical security, personnel and process, operations, key-management infrastructure, and vendor risk. A living reference — rows move from planned to available as controls ship. | `0.5.26-alpha.2` | shipped |
 | ✅ | **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 |
 
 ---
 
+## Financial Messaging & Ledger Enablers
+
+Plumbing for financial-messaging (ISO 20022-class XML flows) and ledger-grade applications, targeted at the `0.8.0` (foundations) and `0.9.0` (integration heavyweights) milestones. Same honesty rule as the compliance controls above: these are enablers, and "compliant" never attaches to a framework — ISO 20022 compliance attaches to the messages an institution exchanges under a scheme's usage guidelines, SWIFT compliance to the institution itself (membership, certified interfaces, the annual CSP attestation), and ledger correctness to the application. Gina supplies the building blocks an application uses to get there.
+
+| Status | Feature | Version | Target |
+| --- | --- | --- | --- |
+| 📋 | **XML request handling** — `application/xml` / `text/xml` request bodies reach the application verbatim (alongside `req.rawBody`) instead of being run through the form-encoded decode path; the application parses with the XML library of its choice. | `0.8.x` | 2027 |
+| 📋 | **`renderXML` delegate** — first-class XML responses (content type + charset), mirroring `renderJSON`. | `0.8.x` | 2027 |
+| 📋 | **Pluggable message-schema validation** — a seam for validating inbound/outbound messages against the XSDs or usage-guideline validators the application supplies, with a fail-closed 400/422 shape — kept pluggable so the framework never takes on a native-addon dependency. | `0.8.x` | 2027 |
+| 📋 | **IBAN / BIC validation rules** — ISO 13616 (MOD-97) and ISO 9362 shape checks as built-in FormValidator rules, client and server. | `0.8.x` | 2027 |
+| 📋 | **Money & minor-unit utilities** — an ISO 4217 minor-unit exponent table plus a documented exact-money pattern (amounts as strings on the wire, integer minor units internally) and helpers, so monetary values never ride IEEE-754 float arithmetic. | `0.8.x` | 2027 |
+| 📋 | **Idempotency keys** — store-backed request deduplication: a client-supplied idempotency key makes a retried mutation return the recorded first response instead of executing twice. | `0.8.x` | 2027 |
+| 📋 | **Sequence primitive** — monotonic (optionally gapless) reference-number allocation backed by a durable store. | `0.8.x` | 2027 |
+| 📋 | **Datastore transaction seam** — a uniform entity-layer transaction surface with per-connector capability flags; until it ships, the documented per-connector native escape hatches remain the supported answer. | `0.9.x` | 2027 |
+| 📋 | **OAuth2 client-credentials egress** — token acquisition and refresh (including signed-JWT client assertions) for outbound `self.query()` calls to OAuth2-protected APIs. | `0.8.x` | 2027 |
+| 📋 | **Message-queue connector family** — first-class messaging connectors (AMQP / Kafka / IBM MQ) in the `connectors.json` model, for integration with message-based platforms. | `0.9.x` | 2027 |
+
+---
+
 ## Connectors
 
 New database connectors follow the same interface as the existing Couchbase connector: declared in `connectors.json`, acquired via `getConnection()`.
@@ -296,7 +318,7 @@ New database connectors follow the same interface as the existing Couchbase conn
 | ✅ | **`connector:infer` — one-off AI inference CLI** | `0.5.6-alpha.3` | Q2 2026 | Runs a single inference against a configured `ai` connector **outside a request** — the runtime sibling of the config-only `connector:list`/`add`/`rm`/`migrate` tooling. Resolves the project's shared (or shared+bundle merged) `connectors.json`, resolves `${secret:KEY}` credentials from the CLI's own environment (the resolved value is never echoed), instantiates the connector directly (no bundle boot, no framework socket), and prints the normalised result. `gina connector:infer <connector> [<bundle>] @<project> --message="..."`, with `--system` / `--model` / `--max-tokens` / `--temperature` per-call overrides; `--message` takes precedence over a messages JSON array piped on stdin. `--format=json` (matched strictly — `jsonl`/`json5` fall back to the text output) emits `{ content, model, usage }`, with `--raw` adding the full provider response as a `raw` field (omitted by default for CLI use); text mode writes the content to stdout and a model/usage footer to stderr. `--stream` streams the inference as newline-delimited JSON (NDJSON) — one frame per line on stdout: a `start` frame, a `delta` frame per token, then a terminal `done` (content, model, usage, latency; plus the provider `raw` object under `--raw` — `null` for OpenAI-family streams) or `error` frame; token counters are passed through verbatim and are `null` (never fabricated) when a provider does not report them. Errors cleanly on a non-`ai` connector, and surfaces missing-SDK / credential / transport failures with a non-zero exit and the reason on stderr. Useful for smoke-testing connectivity + credentials from CI/automation, or scripting a one-off inference from a shell; offline providers such as `ollama://` work with no paid-API key. Implemented 2026-06-30 (`connector:infer` + the `--stream` NDJSON mode; a later output-hardening pass added `--raw`, pipe-safe synchronous writes, and `--message`-over-stdin precedence). |
 | ✅ | **`connector:test` — connector readiness probe CLI** | `0.5.6-alpha.3` | Q2 2026 | Probes a project's configured connectors for readiness **outside a request** — the CI-friendly sibling of `connector:list` (driver-install status only) and `secrets:check` (env presence only), answering "is this connector ready to use?". Default is validate-only and offline: per connector it checks the `connector` type / `ai` protocol is recognised, the npm driver is installed at `<project>/node_modules`, and every `${secret:KEY}` placeholder resolves from the environment — no network, no connector instantiated — exiting non-zero when any connector fails so it can gate a deploy. `gina connector:test [<connector> [<bundle>]] @<project>` tests one connector or every connector in a project (bare → every registered project), mirroring `connector:infer`'s positional grammar and `secrets:check`'s all-mode; `--format=json` emits a machine-readable readiness report. The `--connect` opt-in adds a live connectivity probe: for `ai` connectors it calls the provider's `models.list` (a credentialed request that authenticates with **zero generation tokens**; `ollama://` confirms the local server is up), resolving `${secret:KEY}` the way `connector:infer` does (the value is never printed). For DB/cache connectors the live `--connect` probe is reported as **skipped** for now (config / driver / secrets are still validated) — the live DB/cache probe is a follow-up, since those connector classes load `core/gna` (which exits the process outside a booted bundle) and cannot be instantiated the way the AI connector is. Implemented 2026-06-30. |
 | ✅ | **`connector:models` — list an AI connector's provider models** | `0.5.8` | Q2 2026 | Lists the model catalogue a configured `ai` connector's provider can serve — the read sibling of `connector:test --connect` (which makes the same `models.list()` call but keeps only the count). `gina connector:models <connector> @<project> [<bundle>]` prints one model id per line (a count footer on stderr), or `--format=json` emits `{ project, connector, provider, count, models }` with each entry passed through verbatim from the provider (only `id` is guaranteed across providers — Anthropic and OpenAI-family return different fields). Reuses the direct-`AIConnector` bootstrap of `connector:infer` / `connector:test` (no bundle boot, no framework socket); resolves config only and never prints credentials; offline providers such as `ollama://` work with no internet. `isAIConnector`-gated (a non-AI connector is rejected cleanly), and a provider client without `models.list` reports `supported:false` with a non-zero exit rather than a fabricated empty list. Implemented 2026-07-03. |
-| 📋 | **DuckDB** | `0.5.x` | Q3 2026 | ORM / entity connector for DuckDB — an embedded **analytical** (columnar, OLAP) store: the analytics-side sibling of the SQLite connector's embedded OLTP role. Planned shape follows the MySQL / PostgreSQL architecture: entity wiring, `sql/` layout, positional placeholders (DuckDB accepts `?` and `$name`), `@param`/`@return` annotations, native Promise + `.onComplete()`, driver loaded from the project's `node_modules` as an optional peer dependency. Client: `@duckdb/node-api` (DuckDB's current-generation Node client). Use cases: in-process analytics and reporting bundles over app data, querying Parquet / CSV / JSON files directly without an ETL hop, larger-than-memory local aggregation; both `:memory:` and file-backed databases. Session store is a non-goal — DuckDB is a single-writer analytics engine (Redis / SQLite cover session storage). |
+| 📋 | **DuckDB** | `0.6.x` | Q3 2026 | ORM / entity connector for DuckDB — an embedded **analytical** (columnar, OLAP) store: the analytics-side sibling of the SQLite connector's embedded OLTP role. Planned shape follows the MySQL / PostgreSQL architecture: entity wiring, `sql/` layout, positional placeholders (DuckDB accepts `?` and `$name`), `@param`/`@return` annotations, native Promise + `.onComplete()`, driver loaded from the project's `node_modules` as an optional peer dependency. Client: `@duckdb/node-api` (DuckDB's current-generation Node client). Use cases: in-process analytics and reporting bundles over app data, querying Parquet / CSV / JSON files directly without an ETL hop, larger-than-memory local aggregation; both `:memory:` and file-backed databases. Session store is a non-goal — DuckDB is a single-writer analytics engine (Redis / SQLite cover session storage). |
 
 ---
 
@@ -365,7 +387,7 @@ A cold audit of the Couchbase connector identified two critical security vulnera
 | ✅ | **Application-level rapid reset rate limiter** (CVE-2023-44487) — per-session stream creation counter | `0.3.13` | 2026-05-14 | The Isaac HTTP/2 session handler counts new streams in a rolling 1s window per session; over `maxStreamsPerSecond` (default 200) it sends a GOAWAY and closes the session. More targeted than `maxSessionRejectedStreams` (which counts refused streams, not created ones). Configurable via `settings.json` `http2Options.maxStreamsPerSecond`; `/_gina/info` exposes a `rapidResetBlocked` counter. |
 | ✅ | **Trailer support** — `stream.sendTrailers()` + `waitForTrailers: true` | `0.4.0` | 2026-05-22 | Opt-in HTTP/2 response trailers via `self.sendTrailers(fields)`. The render pipeline sets `waitForTrailers` and emits the trailing headers after the body (in the `wantTrailers` event), across all render delegates. Activated only when a controller calls `self.sendTrailers(fields)`; HTTP/1.1 and the no-trailers path are unchanged. For gRPC-style streaming (`grpc-status`) and content-integrity (`Digest`) use cases. |
 | ✅ | **Alt-Svc header** — advertise HTTP/3 availability | `0.4.2` | 2026-06-02 | Set `Alt-Svc: h3=":443"; ma=86400` response header to advertise HTTP/3 (QUIC) availability via a QUIC-capable reverse proxy (nginx, Caddy, Cloudflare). Gina does not need to implement QUIC — just announce it. Opt-in via `settings.server.json`. Native HTTP/3 is out of scope: Node.js has no stable QUIC API, and the standard deployment topology (Gina → proxy → client) already delivers HTTP/3 at the edge. |
-| 📋 | **RFC 9218 Extensible Priorities** — read `Priority: u=N, i` request header | `0.5.x` | Q1 2027 | Use the RFC 9218 priority header to order response writes for multiplexed API clients. Low value for typical HTML page loads; high value for parallel API requests with declared urgency. |
+| 📋 | **RFC 9218 Extensible Priorities** — read `Priority: u=N, i` request header | `0.6.x` | Q1 2027 | Use the RFC 9218 priority header to order response writes for multiplexed API clients. Low value for typical HTML page loads; high value for parallel API requests with declared urgency. |
 | ✅ | **WebSocket over HTTP/2** (RFC 8441 extended CONNECT) — opt-in via `http2Options.enableConnectProtocol` (default off; https and cleartext h2c HTTP/2 bundles). From `onInitialize`, `app.onWebSocket(path, handler)` registers per-path WebSocket handlers; accepted streams arrive as full sessions backed by a built-in dependency-free RFC 6455 codec (auto-pong, timed close handshake, UTF-8 + close-code validation, payload/fragment DoS caps, backpressure passthrough, graceful shutdown drain). Unknown paths are refused with 404, plain CONNECT keeps its 405, and default-off deployments are byte-identical. **Extended in `0.5.5`:** endpoints are declarable in `routing.json` (`method: "ws"` + `param.wsHandler` → `channels/<name>.js`, `:param` paths, per-route `param.wsOptions`), and handlers can call other bundles over HTTP with `session.query()`. | `0.4.7` | 2026-06-11 |
 
 ---
@@ -406,6 +428,11 @@ A cold audit of the Couchbase connector identified two critical security vulnera
 | ✅ | **Route radix trie — compile `routing.json` at startup** | `0.3.0-alpha.1` | 2026-04-01 | `lib/routing/src/radix.js` builds a segment-level trie once at startup. O(m) candidate lookup per request (m = segment count). `Set.has()` check skips non-candidates in the `for…in` loop. Internal change — no user-facing API change. |
 | ✅ | **Bun runtime support** | `0.5.5` | 2026-06-21 | Gina runs on the [Bun](https://bun.sh) runtime (Bun `>= 1.2`) as a supported, CI-gated target — `bun add -g gina` installs and boots end-to-end, validated by a blocking CI Bun smoke. Both investigated blockers cleared: dev-mode `require.cache` hot-reload and `node:http2` work under Bun (one upstream gap remains: RFC 8441 extended-CONNECT advertisement, affecting only opt-in WebSocket-over-HTTP/2). Gina self-bootstraps on first run; Node `>= 22 < 27` remains fully supported. |
 | ✅ | **V8 pointer compression support** | `0.2.0` | Q2 2026 | Node.js built with `--experimental-enable-pointer-compression` (e.g. [node-caged](https://github.com/platformatic/node-caged) or a custom build) delivers ~50% heap memory reduction across all pointer-heavy structures. Gina is pure JS — compatible out of the box. Adds: startup detection + `GINA_V8_POINTER_COMPRESSED` env var, Dockerfile guide with custom build recipe (full-icu + pointer compression), 4 GB ceiling documentation, N-API-only connector policy. |
+| 📋 | **Runtime CPU profiling baseline** | `0.7.x` | 2027 | Flame-graph profiles of representative bundles under load — render, concurrent-upload, and WebSocket arms — so every hot-path candidate below is convicted or acquitted by measurement before it is optimised. "No further acceleration needed" is a valid verdict. |
+| 📋 | **Multipart boundary-scan fast path** | `0.7.x` | 2027 | The multipart parser's boundary search is the one unbounded byte-by-byte JS loop on a request path. Delegating the in-chunk needle search to the runtime's native `Buffer.indexOf` (JS keeps only the chunk-boundary carry) relieves the event loop under large concurrent uploads. Wire and event contract unchanged; validated by differential tests against the current matcher. |
+| 📋 | **WebSocket unmask fast path** | `0.7.x` | 2027 | Every inbound client frame must be unmasked, and that XOR currently runs byte-by-byte in JS. Word-at-a-time unmasking in the built-in RFC 6455 codec, with the `ws` engine path picking up `bufferutil` acceleration where it is installed — optional only; the pure-JS behaviour remains the permanent fallback. |
+| 📋 | **Render & logging hot-path cleanups** | `0.7.x` | 2027 | Repair the per-render asset-scan memoization (the cache guard can never hit as written, so the full document is re-scanned every HTTP/2 render), precompile the logger's per-line token regexes, and consolidate whole-document render passes where the profiling baseline convicts them. |
+| ⏸ | **SIMD boundary scanner (Rust → WebAssembly)** | — | on demand | **Deferred — measure-gated.** Built only if the profiling baseline still convicts the multipart scan after the JS fast path lands. WebAssembly first: sandboxed, a single artifact for every platform including Bun, no process crash surface. Native N-API prebuilds — published as separate per-platform packages so the framework tarball never carries a compiled binary — only if WASM leaves measured headroom. No install scripts ever; the JS implementation remains the permanent fallback. *Interim:* the JS fast path above. |
 
 ---
 
@@ -467,7 +494,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.5.x` | Q4 2026 |
+| 📋 | **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 |
 
 ---
 
@@ -475,7 +502,7 @@ Gina's built-in per-bundle inspector. Phases 1–2 ship as an embedded SPA at `/
 
 | Status | Feature | Version | Target |
 | --- | --- | --- | --- |
-| 📋 | **Official website redesign + docs integration** — Refactor gina.io as a proper project homepage (landing page, feature highlights, showcase) with the documentation fully integrated. Single coherent web presence. Prerequisite: tutorials complete. | `0.5.x` | Q4 2026 |
+| 📋 | **Official website redesign + docs integration** — Refactor gina.io as a proper project homepage (landing page, feature highlights, showcase) with the documentation fully integrated. Single coherent web presence. Prerequisite: tutorials complete. | `0.6.x` | Q4 2026 |
 | ✅ | **Docs offline ZIP** — One-click download of the complete gina.io documentation as a static HTML ZIP archive. Generated at deploy time by the Docusaurus build pipeline — no server-side logic required. Targeted at users in regions with limited or expensive internet access (offline-first for the African market). | `0.4.0` | 2026-05-22 |
 | ✅ | **Security & CVE compliance page** — Dedicated docs page listing the HTTP/2 CVEs addressed by Gina and the Node.js version required for each mitigation. Covers CVE-2023-44487 (Rapid Reset), CVE-2024-27316 / CVE-2024-27983 (CONTINUATION flood), CVE-2019-9514 (RST flood), HPACK bomb, and server push abuse. Docs only — no code changes. | `0.3.0-alpha.1` | 2026-04-01 |
 

package/bin/cli

@@ -356,6 +356,7 @@ async function onExec() {
 
     // |-> framework/{version}/lib/cmd
     var allowedOffline = [
+        'audit:',
         'build:',
         'bundle:',
         'cache:',
@@ -456,7 +457,13 @@ async function onExec() {
     } else {
 
         //Connect to framework.
-        var client = net.connect({port: port, host: hostV4},
+        // #B160 — the daemon binds `bind_host` (loopback by default) while
+        // `host_v4` is the address EXTERNAL clients use. When host_v4 names
+        // one of this machine's own interfaces, the daemon is local: dial the
+        // bind address, not the external one. A remote host_v4 is dialled
+        // unchanged.
+        var dialHost = lib.netLocality.resolveDialHost(hostV4, bindHost);
+        var client = net.connect({port: port, host: dialHost},
             function() {
                 //Forwarding cmd.
                 // retieving debug infos
@@ -504,6 +511,10 @@ async function onExec() {
             } else {
                 console.log('[ gina ] not started, try to start framework with :\n$ sudo gina start')
             }
+            // #B160 — name the dial target and the bind knob: a refused
+            // connection here is either a daemon that is not running, or one
+            // bound to a different address than the one dialled.
+            console.log('Could not reach the framework command socket at `'+ dialHost +':'+ port +'`.\nThe daemon binds `bind_host` (default `127.0.0.1` — see ~/.gina/'+ shortVersion +'/settings.json, or the GINA_BIND_HOST env var).');
 
             console.debug(err.stack||err);
 

package/bin/gina-init

@@ -353,6 +353,20 @@ projectsOut[projectName] = projectEntry;
 var userInfo = { username: 'node', uid: -1, gid: -1 };
 try { userInfo = os.userInfo(); } catch(e) { /* running as unresolvable uid (e.g. scratch image) */ }
 
+// #B161 — honour an operator-set bind_host instead of discarding it: this file
+// overwrites settings.json unconditionally on every container start, so a
+// value written by `gina framework:set --bind-host=` (or a previous bootstrap)
+// was silently reverted to loopback. Env first (this script reads raw
+// process.env by design — see the note near the top), then the value already
+// persisted in settings.json, then the loopback default. The `${` guard skips
+// an unresolved template placeholder.
+var prevBindHost = null;
+try {
+    var _prevSettingsRaw = fs.readFileSync(ginaHome + '/' + shortVersion + '/settings.json', 'utf8');
+    prevBindHost = JSON.parse(_prevSettingsRaw).bind_host || null;
+    if (prevBindHost && String(prevBindHost).indexOf('${') > -1) { prevBindHost = null; }
+} catch (e) { /* absent or unreadable — defaults apply */ }
+
 var settingsOut = {
     version             : version,
     def_framework       : version,
@@ -368,7 +382,7 @@ var settingsOut = {
     debug_port          : '9229',
     mq_port             : '8125',
     host_v4             : '127.0.0.1',
-    bind_host           : '127.0.0.1',
+    bind_host           : process.env.GINA_BIND_HOST || prevBindHost || '127.0.0.1',
     hostname            : os.hostname(),
     user                : userInfo.username,
     uid                 : String(userInfo.uid),

package/framework/v0.6.0/VERSION

@@ -0,0 +1 @@
+0.6.0

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

@@ -6284,9 +6284,23 @@ function Routing() {
         return route;
     }
 
+    /**
+     * #B168 — once-per-process latch for the proxied-context degrade warning in
+     * getRoute(): the resolver sits on the per-request hot path, so the abnormal
+     * state is reported once rather than per call (under dev-mode hot-reload the
+     * module re-evaluates, so the warning may reappear per reload cycle).
+     * @private
+     */
+    var _proxyHostDegradeWarned = false;
+
     /**
      * @function getRoute
      *
+     * On the server, a proxied-context call resolves the route's proxy hostname
+     * from the worker global with an envConf fallback; when neither holds a value
+     * the route degrades to its direct hostname (route.isProxyHost is flipped
+     * false) instead of failing, and a once-per-process warning is emitted.
+     *
      * @param {string} rule e.g.: [ <scheme>:// ]<name>[ @<bundle> ][ /<environment> ]
      * @param {object} params - substituted into the route's `:placeholders`; on a GET route, leftover keys that are neither reserved nor declared in the rule's `requirements` are appended to `route.url` as query parameters (a rule with no `requirements` block is safe — the block is optional)
      * @param {number} [urlIndex] in case you have more than one url registered for the current route, you can select the one you want to use. Default is 0.
@@ -6377,11 +6391,32 @@ function Routing() {
                 route.proxy_hostname  = process.gina.PROXY_HOSTNAME || config.envConf._proxyHostname;
                 // console.debug("[getRoute#1]["+isProxyHost+"] process.gina.PROXY_HOSTNAME ("+ process.gina.PROXY_HOSTNAME  +") VS config.envConf._proxyHostname ("+ config.envConf._proxyHostname +")");
             }
-            route.proxy_host      = route.proxy_hostname.replace(/^(https|http)\:\/\//, '');
+            // #B168 — on the server, BOTH sources above are framework-produced falsy
+            // states: the worker global is boot-set only from a proxy config carrying a
+            // hostname (and otherwise first written by a proxied request), while the
+            // envConf fallback is deliberately written null for a request classified
+            // direct. With the worker-wide proxied latch true and both unset, the
+            // unguarded rewrite below crashed every server-side getRoute() while the
+            // state lasted. Degrade to the route's direct hostname instead — and flip
+            // route.isProxyHost too: toUrl() keys on it, so leaving it true would
+            // stringify the unset value straight into the emitted URL.
+            if (route.proxy_hostname) {
+                route.proxy_host      = route.proxy_hostname.replace(/^(https|http)\:\/\//, '');
+            } else {
+                delete route.proxy_hostname;
+                route.isProxyHost = false;
+                if (!_proxyHostDegradeWarned) {
+                    _proxyHostDegradeWarned = true;
+                    console.warn('[ RoutingHelper::getRoute() ] Proxied context is active but no proxy hostname is resolvable (worker global and envConf fallback both unset) - falling back to the route direct hostname. Warned once per process.');
+                }
+            }
 
         } else if (
             !isGFFCtx
             && typeof(process.gina.PROXY_HOSTNAME) != 'undefined'
+            // #B168 — the typeof gate admits a defined-but-falsy value (typeof null is
+            // 'object'); require a truthy hostname before the rewrite below
+            && process.gina.PROXY_HOSTNAME
         ) {
             route.proxy_hostname  = process.gina.PROXY_HOSTNAME;
             route.proxy_host      = route.proxy_hostname.replace(/^(https|http)\:\/\//, '');