gina 0.3.16-alpha.1 → 0.4.0

package/CHANGELOG.md

@@ -6,6 +6,44 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html),
 and is generated by [Changie](https://github.com/miniscruff/changie).
 
 
+## 0.4.0 - 2026-05-29
+### Added
+* Inspector View tab now shows the template engine version next to the engine name (e.g. `Swig | 2.4.0`). The version is sourced server-side from the cached swig / nunjucks resolver decisions and falls back to a name-only badge when no version is resolvable (very-early bootstrap, test stubs, legacy render paths).
+* Inspector Query tab — SQL index badges now do column-level coverage matching. A new badge marks a query whose WHERE columns are not covered by any declared index (leftmost-prefix match against the bundle indexes.sql), instead of only checking whether the target table has any index.
+* Added gina secrets:scan and gina secrets:check CLI commands that introspect the ${secret:KEY} placeholders your bundle configs require. secrets:scan reports each required key and the config file(s) that declare it; secrets:check cross-references the current environment, marks each key SET or UNSET, and exits non-zero when any required key is missing (for CI / pre-deploy gating). Both support --format=json.
+* gina secrets:scan and secrets:check gain --scope=<scope> to report the effective required secrets for a deployment scope (read-only deep-merge of the sibling config_<scope>/ dirs over base config, scope wins), and secrets:check gains --env-file=<path> to validate against a .env-style file (e.g. a decrypted SOPS export) instead of the live process.env. The runtime config loader is unchanged — per-scope config selection stays a deploy-time concern.
+* Added opt-in HTTP/2 response trailer support via self.sendTrailers(fields). A controller registers trailing headers before rendering, and the render pipeline sets waitForTrailers on the HTTP/2 stream and emits them after the response body (in the wantTrailers event) — useful for gRPC-style streaming (a final grpc-status / grpc-message) or a content-integrity Digest after a chunked body. Pseudo-header keys (those beginning with a colon) are stripped. The feature is fully opt-in: a no-op on HTTP/1.1 and when no trailers are registered, so existing responses are byte-for-byte unchanged.
+* Added lib.job, an async-job primitive for running slow work out-of-band. lib.job.create(fn) enqueues a deferred async function and returns a job id immediately; the function runs on a concurrency-limited worker and its outcome moves through pending, running, then completed or failed, and is queryable via lib.job.get(id, cb). Stale terminal jobs are purged on a configurable TTL by a self-contained sweep. Tune via the app.json jobs block (maxConcurrency, ttl, sweepInterval, idSize); sane defaults apply when the block is omitted.
+* Added the self.startJob(fn) and self.jobStatus(id, cb) controller helpers for async jobs. self.startJob runs a deferred async function out-of-band and returns a job id immediately (a thin wrapper over lib.job.create); self.jobStatus reads a job record from within your own authenticated route. The deferred function runs after the request has completed, so capture plain values rather than the request or response objects.
+* Added a built-in /_gina/jobs/:id status endpoint that reports an async job state (pending, running, completed, or failed). It is always-on and state-only (it never returns the result or error payload) and works under both the Isaac and Express engines. Retrieve a completed job result from your own authenticated route via self.jobStatus.
+* Added the self.inferAsync(messages, options) controller helper, which runs a model inference as an async job in one call and returns a job id immediately. It wraps the AI connector through self.startJob; the stored job result is the trimmed inference (content, model, usage). Select the connector with options.connector, poll /_gina/jobs/:id for state, and read the result from your own authenticated route via self.jobStatus.
+* Added opt-in completion webhooks for async jobs. Pass a callbackUrl when creating a job (lib.job.create(fn, { callbackUrl }) or self.startJob(fn, { callbackUrl })) and the framework POSTs { id, state, result, error } to it when the job finishes. Delivery is best-effort with retry and exponential backoff; persistent failures are recorded on the job as webhookFailed and never affect the job outcome. Configure a per-bundle webhookSecret (app.json jobs.webhookSecret, ideally a secret placeholder) to sign each payload with an X-Gina-Signature HMAC-SHA256 header.
+* Added an opt-in API-key gate for the dev-mode /_gina/agent Inspector SSE stream. Set inspector.agent.enabled and inspector.agent.key in settings.json to reach the endpoint outside dev mode (e.g. staging) for authenticated remote server-log streaming; the key is presented via the x-gina-inspector-key header or a ?key= query param and compared in constant time. In dev the endpoint stays open with no key (unchanged).
+* Added a toggleable Inspector instrumentation window (#INS10): POST /_gina/instrument opens a time-boxed, key-authenticated window that runs query + flow capture outside dev mode and streams it over the authenticated /_gina/agent SSE (JSON/XHR responses + cross-bundle queries). Opt-in via settings.json inspector.instrumentation; 300s default window, 3600s hard cap, auto-revert.
+* Inspector instrumentation windows now stream the controller queries and flow timeline of a server-rendered HTML page over the authenticated agent SSE, not just JSON and XHR responses. The page HTML is never modified; the capture leaves only over the key-authenticated channel while a window is open.
+* gina.plugins.Csp({ useNonce: true }) generates a fresh per-response CSP nonce, stamps it on req._ginaCspNonce, and appends a nonce source-expression to script-src (fallback default-src). The swig and nunjucks renderers set a matching nonce attribute on the framework-injected onGinaLoaded bootstrap script — letting bundles drop unsafe-inline from script-src. Opt-in (default false); existing bundles are unaffected.
+* The dev-mode Inspector inline scripts (window.__ginaData snapshot + console-capture) and the client-side metrics-patch scripts now carry the gina.plugins.Csp({ useNonce: true }) per-response nonce in both the swig and nunjucks renderers, so a bundle running strict CSP in dev no longer reports violations for those framework-injected inline scripts. Extends the #HDR16 onGinaLoaded bootstrap nonce.
+* gina.plugins.Csp({ useNonce: true }) now exposes the per-response nonce to your templates as {{ page.cspNonce }} (swig) / {{ cspNonce }} (nunjucks), so you can add a matching nonce attribute to your own inline <script> tags and drop 'unsafe-inline' from script-src. The dev-mode Inspector status bar inline script carries it automatically. Opt-in (default false); bundles that don't set useNonce are unaffected.
+### Changed
+* Inspector View tab — the server-emitted Weight and Load fallback values now render in italic with a slightly deeper dim (new `bm-vbadge-svr` style), so a value sourced from the server reads distinctly from the client-measured primary and the engine-version dim.
+* gina.plugins.Coop() — documented that the default `same-origin` value severs the `window.opener` link the dev Inspector relies on to read client-side timing, so the View tab Weight and Load badges fall back to server-rendered metrics (FCP stays browser-only). Dev-only — the Inspector is gated on NODE_ENV_IS_DEV.
+* Bumped @rhinostone/swig dependency floor from ^2.4.1 to ^2.5.1 in both root package.json and framework/v*/package.json. Cumulative content: 2.5.0 introduced the Jinja2 frontend as a published sibling package (@rhinostone/swig-jinja2 — block, extends, include, import, from, macro, for, set, with, filter, raw, autoescape tags + full Jinja2 filter set + async loader via renderFileAsync/compileFileAsync); 2.5.1 added the new sibling to the workspace README family list, restored JSDoc on the top-level public API (regression from engine.install carve), and is dev-only otherwise. swigResolver DEFAULT_MIN stays at 2.0.0 since the framework does not depend on any new 2.5.x-only API. The lib/swig-resolver/src/main.js docstring is extended in the same commit to mention @rhinostone/swig-jinja2 alongside @rhinostone/swig-twig as a known sibling alternate; bundles can opt into either via swig.package + swig.useProject (same shape as the existing Twig opt-in).
+* Upgrading to 0.4.0 is a shortVersion bump (0.3 to 0.4): the framework creates a fresh ~/.gina/0.4/settings.json from defaults on install, so any customizations made under 0.3 (log level, port, culture, timezone, etc.) are not carried forward. Re-apply them after upgrading with gina framework:set, or copy the values across from ~/.gina/0.3/settings.json.
+### Removed
+* Removed the Couchbase SDK v2 ORM connector and session store (connector.v2.js and session-store.v2.js). Couchbase Server SDK v2 reached end-of-life in 2021, so only SDK v3 and v4 are now supported, and the connector defaults to v3 when no couchbase version is pinned. Migrating is a driver bump rather than a config change — upgrade the couchbase dependency in your project to ^3 or ^4 (for example, npm install couchbase@^4). Bundles still resolving to SDK v2 now fail fast at connector load with an explicit upgrade message instead of loading the removed code path.
+### Fixed
+* Hardening `npm install -g gina` against npm setups that don't propagate `npm_config_global` to the post-install subprocess: `isGlobalInstall` now also detects from `__dirname`, and the local-install symlink step no-ops when its source path is missing instead of crashing the install.
+* throwError(statusCode, Error|string) 2-arg form now honors the explicit status code. Previously the inner status-coercion read .status from the wrapped error rather than from the number itself, so any explicit code other than 500 was silently lost. The 2-arg-with-errorObj shape was unaffected and stays unchanged. Documented in types/index.d.ts as a new overload.
+* Inspector View tab — restored the Weight and Load badges when `window.opener.performance` is unreachable (e.g. host page sets `Cross-Origin-Opener-Policy`, which nulls the popup opener reference). Server-side metrics (`weightBytes` from the response body byte length, `serverMs` from the request timeline) are now emitted on `__ginaData.user.environment.metrics` and used as fallback by the client. When both client + server values are available, the badge renders as a dual `<server-dim> | <client-primary>` pair — surfacing the compression ratio for Weight and the network/parse/paint cost for Load.
+* Inspector View tab — restored the Weight and Load badges for bundles using the nunjucks template engine. Closes the deferred follow-up from the earlier swig-side restoration, so both engines now surface the metrics consistently under `Cross-Origin-Opener-Policy` (no `window.opener`).
+* Inspector Flow tab — restored the request-lifecycle timeline for bundles using the nunjucks template engine. The nunjucks render delegate now builds `data.page.flow` (with N1QL queries converted into timeline entries) and late-binds the response-write/total entries via the same `_flowPatch` mechanism as the swig delegate, so the Flow waterfall is populated for nunjucks pages (previously entirely empty). Closes the deferred Flow-tab follow-up from the earlier swig-side restoration.
+* SQL Inspector index-coverage badges now stay accurate after a live /_gina/indexes refresh — the MySQL, PostgreSQL and SQLite introspection paths capture each index column, so column-level coverage no longer degrades to a false no-index-for-filter badge once live introspection has run.
+* The Inspector Query tab now flags SQL queries whose WHERE filter no existing index can serve, even for bundles without an indexes.sql file (resolved via live database introspection); previously these showed an optimistic index badge instead of the no-index-for-filter warning.
+* Swig template engine updated to 2.4.1. Macros that call other macros imported at the top of their own defining file now resolve correctly (previously they rendered empty), recursively across import depth.
+* Refreshed stale external references shipped with the framework. The man-page COLOPHON sections and the CLI framework-not-found messages now point to https://gina.io (previously http://www.gina.io); GitHub references in the man pages, the bundled lib READMEs, and the generated-project package.json template now use the gina-io organisation (previously the former rhinostone org); the vendored lib/inherits package metadata now references the canonical repository; and the framework project template no longer ships unreachable internal git-server URLs. Documentation and metadata only - no runtime or API change.
+* Refreshed more stale external references flagged by the link-health sweep. The popin plugin CSS doc now links the live normalize.css domain (necolas.github.io) and drops a dead community-wiki citation (prose retained); the popin extend doc now points to current Apple developer documentation for Smart App Banners and Safari meta tags; and gina bundle:mcp emits a resolvable manifest $schema host (modelcontextprotocol.io; the retired spec. subdomain no longer resolved). Documentation and generated-metadata only - no runtime or API change.
+* Fixed an HTTP 500 when rendering a request whose session uses a browser-session cookie (a session cookie with no expiry). The session-expiry display block now runs only for a real expiry date, so expiry-less sessions render normally instead of crashing.
+
 ## 0.3.15 - 2026-05-19
 ### Added
 * New `isInList` form-validator rule for enum / membership validation. Accepts a JSON array of allowed primitive values (`"isInList": ["draft", "pending", "sent", "paid"]`) and rejects field values that are not strict-equal to any list member. Lives in the shared `form-validator.js`, so the rule fires on both server-side routing validation and client-side browser enforcement. Plugs into the existing `_case_<field>` conditional resolver without special-case handling.

package/CONVENTIONS.md

@@ -209,7 +209,7 @@ Document all globals injected by `gna.js` with `@global` JSDoc so IDEs can disco
 | Element | Convention | Example |
 | --- | --- | --- |
 | Files (multi-word) | dot-separated namespacing | `controller.render-json.js`, `server.isaac.js` |
-| Files (versioned) | `.vN` suffix | `connector.v4.js`, `session-store.v2.js` |
+| Files (versioned) | `.vN` suffix | `connector.v4.js`, `session-store.v4.js` |
 | Files (kebab) | kebab-case | `link-dev.js`, `api-error.js` |
 | Files (test) | numeric prefix + snake | `01-init_new_project.js` |
 | Constructors | PascalCase | `SuperController`, `EntitySuper`, `CmdHelper` |

package/README.md

@@ -39,13 +39,17 @@ gina bundle:start api @myproject
 open https://localhost:3100
 ```
 
-## What's in 0.3.15
+## What's in 0.4.0
 
-- **Web Security Headers track** (#HDR family) — fifteen opt-in `gina.plugins.*` middlewares for response-header hardening, mirroring the `Session` / `Csrf` plugin shape. **Phase 1 modern critical coverage**: `XContentTypeOptions()` (#HDR1, `X-Content-Type-Options: nosniff`), `XFrameOptions()` (#HDR2, clickjacking defense), `ReferrerPolicy()` (#HDR3), `Hsts()` (#HDR4, `Strict-Transport-Security`), `OriginAgentCluster()` (#HDR7). **Phase 1.5 helmet-parity gap-fill**: `HidePoweredBy()` (#HDR8), `XDnsPrefetchControl()` (#HDR9), `XXssProtection()` (#HDR10, emits `0` per OWASP), `XDownloadOptions()` (#HDR11, IE-legacy `noopen`), `XPermittedCrossDomainPolicies()` (#HDR12). **Phase 2 cross-origin set**: `Csp()` (#HDR5, Content-Security-Policy), `Coep()` (#HDR6, Cross-Origin-Embedder-Policy), `Coop()` (#HDR13, Cross-Origin-Opener-Policy), `Corp()` (#HDR14, Cross-Origin-Resource-Policy). **Combined wrapper**: `gina.plugins.SecurityHeaders()` (#HDR15) — batteries-included default opting every plugin in via a single registration; individual plugins remain register-to-opt-in. All plugins idempotent (first-writer-wins), throw on invariant violations at factory call time, flat top-level settings under `settings.json`. No `helmet` dependency. See the [Security Headers guide](https://gina.io/docs/guides/security-headers).
-- **`server.hidePoweredBy` settings flag** (#HDR8 Phase 2) — closes the Isaac-engine `X-Powered-By` emission gap that per-bundle middleware cannot reach. Removes the dead `X-Powered-By` default from the `env.json` template and adds a framework-level emission gate via a closure-helper; bundles opt in to header suppression at the engine level without registering the per-bundle plugin. Reconciles with `gina.plugins.HidePoweredBy()` docs.
-- **`gina.validator.isInList`** — closed-set membership form-validation rule. Useful when a form field accepts a finite enumerated set (status codes, country codes, plan tiers). Out-of-set submissions are rejected before they reach controller code. Distinct from `lib/validator.js`'s separate role (see llms.txt #130).
-- **Security: CVE-2026-45736 closed** (CWE-908 in `ws@8.18.3`) — `engine.io` bumped to `^6.6.7`, `engine.io-client` to `^6.6.4`, and `ws` forced to `^8.20.1` via npm `overrides`. Override route was the only remediation: `engine.io@6.6.7` still transitively pins `ws@~8.18.3` per Snyk's advisory, so a transitive bump alone would have left the vulnerable version reachable.
-- **Internal housekeeping** — #HDR plugin family refactored under `core/plugins/lib/security-headers/` (restoring dir-name ↔ JS-name symmetry after the combined wrapper collapsed into the namespace). Leak-scan `ATTRIBUTION_PATHS` regex consolidated into a single `_load_private_tokens.js` loader (single source of truth). `post_publish.js bumpVersion` `local-sync` now warns on a non-match instead of silently skipping. llms.txt pruned (36 cluster lessons consolidated into 4 parent entries) per the size-guard rule.
+**Upgrading note — this is a shortVersion bump (0.3 → 0.4):** the framework creates a fresh `~/.gina/0.4/settings.json` from defaults on install, so customizations made under 0.3 (log level, port, culture, timezone, etc.) are not carried forward. Re-apply them with `gina framework:set`, or copy values across from `~/.gina/0.3/settings.json`. See the [migration guide](https://gina.io/docs/migration).
+
+- **Breaking — Couchbase SDK v2 removed** (#CN8) — the v2 ORM connector and session store are gone; only Couchbase Node SDK **v3 and v4** are supported (defaults to v3). Migration is a driver bump, not a config change: `npm install couchbase@^4` (or `^3`). Bundles still resolving to SDK v2 fail fast at connector load with an explicit upgrade message.
+- **Async jobs** (#AI6) — run slow work out-of-band: `self.startJob(fn)` returns a job id immediately and runs `fn` on a concurrency-limited worker; `self.inferAsync(messages, opts)` wires the AI connector through a job in one call. Poll the built-in `GET /_gina/jobs/:id` for state, or opt into a signed completion webhook. See the [Async jobs guide](https://gina.io/docs/guides/async-jobs).
+- **HTTP/2 response trailers** (#H10) — `self.sendTrailers(fields)` before rendering emits trailing headers after the body (via the `wantTrailers` event) — useful for gRPC-style `grpc-status` or a content-integrity `Digest`. Fully opt-in: a no-op on HTTP/1.1 and when no trailers are registered. See the [native HTTP/2 guide](https://gina.io/docs/guides/http2-native).
+- **CSP per-response nonce** (#HDR16) — `gina.plugins.Csp({ useNonce: true })` mints a fresh nonce per response, stamps the framework-injected bootstrap (and dev-Inspector) inline scripts, and exposes it to templates as `{{ page.cspNonce }}` (swig) / `{{ cspNonce }}` (nunjucks) — letting bundles drop `'unsafe-inline'` from `script-src`. Opt-in (default false). See the [CSP guide](https://gina.io/docs/guides/csp).
+- **Inspector remote instrumentation** (#INS9b, #INS10) — an opt-in API-key gate on the dev-mode `/_gina/agent` SSE stream streams authenticated server logs outside dev; `POST /_gina/instrument` opens a time-boxed, key-authenticated window that captures query + flow timelines (JSON, XHR, and server-rendered HTML pages) over the authenticated channel without ever modifying the page HTML. See the [Inspector guide](https://gina.io/docs/guides/inspector).
+- **`gina secrets:scan` / `secrets:check` CLI** — introspect the `${secret:KEY}` placeholders your bundle configs require; `secrets:check` marks each key SET/UNSET and exits non-zero on any missing key (CI / pre-deploy gating). `--scope=<scope>`, `--env-file=<path>`, and `--format=json` supported. See the [secrets guide](https://gina.io/docs/guides/secrets).
+- **Inspector dev-UX + fixes** — template engine version on the View badge; Weight/Load badges and the Flow timeline restored under `Cross-Origin-Opener-Policy` and for nunjucks bundles; SQL column-level index-coverage matching (including live DB introspection). Fixes: `throwError(statusCode, Error)` now honors the explicit code; an HTTP 500 on browser-session (no-expiry) cookies; `npm install -g` hardening for npm setups that don't propagate `npm_config_global`; refreshed stale external references; `@rhinostone/swig` floor → `^2.5.1`.
 
 See the full [Changelog](./CHANGELOG.md) and [Roadmap](./ROADMAP.md).
 
@@ -72,7 +76,7 @@ Gina is co-authored by **Martin Luther** ([Rhinostone](https://rhinostone.com))
 
 ## License (MIT)
 
-Copyright © 2009-2026 [Rhinostone](http://www.rhinostone.com/)
+Copyright © 2009-2026 [Rhinostone](https://rhinostone.com)
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/ROADMAP.md

@@ -172,11 +172,12 @@ HTTP security response headers as opt-in `gina.plugins.*` middlewares, mirroring
 | ✅ | **Phase 1.5 — `X-XSS-Protection: 0` (#HDR10)** — Opt-in plugin `gina.plugins.XXssProtection()` emits the literal header `X-XSS-Protection: 0` to DISABLE Chrome's legacy XSS auditor (the auditor itself had its own vulnerabilities; disabling is the modern recommendation per MDN). **The value `0` is deliberate — not a typo**: HEADER_VALUE is the literal string `"0"`, with a negative-invariant test pinning that the value is NOT any `"1"` enable variant. No tunable options (mirrors helmet's no-opts shape + the #HDR1 XContentTypeOptions plugin shape). Use #HDR5 Csp with a strong policy for the actual XSS defense; this header is defense-in-depth + helmet-parity narrative only. Browser status in 2026: Chrome dropped the auditor in v78 (2019); Edge follows Chrome; Firefox / Safari never implemented; IE11 honoured but is EOL. Idempotent — first-writer-wins via `res.getHeader`; if an upstream middleware accidentally emits the unsafe `"1; mode=block"`, this plugin does NOT override it (mount BEFORE the upstream to win). Mirrors the #HDR1 XContentTypeOptions plugin shape (no opts, single fixed value, same `resolveSettingsDefaults` + `mergeOptions` helpers). 37 unit tests including the negative-invariant lock on no-"1"-variant + the string-not-number "0" emission lock. | `0.3.16-alpha` | 2026-05-17 |
 | ✅ | **Phase 1.5 — `X-Download-Options: noopen` (#HDR11)** — Opt-in plugin `gina.plugins.XDownloadOptions()` emits the literal header `X-Download-Options: noopen` on every response. IE-legacy: prevents IE8+ from opening downloads in the site's security context (an old IE vulnerability shape where the "Open" button on a download dialog opened the file in the SITE's origin, allowing XSS-equivalent via downloaded HTML from a trusted site). `noopen` is the only valid value per MSDN. No tunable options (mirrors helmet's no-opts shape + the #HDR1 / #HDR10 plugin shape). Modern browsers (Chrome / Firefox / Safari / Edge) ignore the header silently; only IE10 / IE11 honour it (both EOL since June 2022). Effectively no-op in modern browsers; defense-in-depth + helmet-parity narrative. Idempotent — first-writer-wins via `res.getHeader`. Mirrors the #HDR1 XContentTypeOptions plugin shape exactly. 35 unit tests. | `0.3.16-alpha` | 2026-05-17 |
 | ✅ | **Phase 1.5 — `X-Permitted-Cross-Domain-Policies` (#HDR12)** — Opt-in plugin `gina.plugins.XPermittedCrossDomainPolicies({ value })` emits the `X-Permitted-Cross-Domain-Policies` response header on every response. Settings: `xPermittedCrossDomainPolicies.value` is one of four Adobe spec tokens (`"none"`, `"master-only"`, `"by-content-type"`, `"all"`); default `"none"` matches helmet (most restrictive — no Flash/PDF cross-domain policy files honoured). **API-shape divergence from helmet**: helmet uses `{ permittedPolicies: <enum> }`; gina uses `{ value: <enum> }` matching the existing single-token-enum convention (HDR2 / HDR3 / HDR6 / HDR9 / HDR13 / HDR14). README documents the helmet-to-gina mapping. Mirrors the #HDR14 Corp single-enum plugin shape exactly (`resolveSettingsDefaults` + `mergeOptions` + `resolveValue` throw-on-invalid + idempotent first-writer-wins via `res.getHeader`). Flash EOL since December 2020; Adobe Reader historically honoured the header but most modern PDF readers ignore it; defense-in-depth + helmet-parity narrative. 60 unit tests including a negative-invariant lock on the helmet-shape `{ permittedPolicies }` silent-fallback (it does NOT switch the gina default — emits default `"none"`). **Closes Phase 1.5.** | `0.3.16-alpha` | 2026-05-17 |
-| ✅ | **`Content-Security-Policy` middleware (Phase 2 — static directives)** — Opt-in plugin `gina.plugins.Csp({ directives, reportOnly })`. **Opens Phase 2** of the security-headers track. v0 ships static directives only; per-response nonce wiring requires template-render integration and defers to a future CSP-aware view-layer plugin. Strict whitelist of 27 CSP Level 3 standard directives — unknown directive names throw at factory call time (CSP typos are silent at the browser; fail-fast catches them). Value parsing accepts arrays of source-list tokens (joined with space), pre-formatted strings, `true` (boolean-only directives + `sandbox`), or `false` (omit). `reportOnly: true` emits `Content-Security-Policy-Report-Only` for non-enforcing migration testing. `directives` is required — no sensible cross-bundle default. Mirrors the HDR1-7 shape (idempotent first-writer-wins via `res.getHeader`). 92 unit tests; full suite 5768/5768. HDR6 Coep/Coop/Corp three-plugin split (per wrapper-consistency design) + HDR15 `SecurityHeaders` combined wrapper composing HDR1-7 + HDR5 + HDR6/13/14 to follow. | `0.4.0-alpha` | 2026-05-17 |
+| ✅ | **`Content-Security-Policy` middleware (Phase 2 — static directives)** — Opt-in plugin `gina.plugins.Csp({ directives, reportOnly })`. **Opens Phase 2** of the security-headers track. v0 shipped static directives only; per-response nonce support landed later as #HDR16 (see below). Strict whitelist of 27 CSP Level 3 standard directives — unknown directive names throw at factory call time (CSP typos are silent at the browser; fail-fast catches them). Value parsing accepts arrays of source-list tokens (joined with space), pre-formatted strings, `true` (boolean-only directives + `sandbox`), or `false` (omit). `reportOnly: true` emits `Content-Security-Policy-Report-Only` for non-enforcing migration testing. `directives` is required — no sensible cross-bundle default. Mirrors the HDR1-7 shape (idempotent first-writer-wins via `res.getHeader`). 92 unit tests; full suite 5768/5768. HDR6 Coep/Coop/Corp three-plugin split (per wrapper-consistency design) + HDR15 `SecurityHeaders` combined wrapper composing HDR1-7 + HDR5 + HDR6/13/14 to follow. | `0.4.0-alpha` | 2026-05-17 |
 | ✅ | **`Cross-Origin-Embedder-Policy` (COEP) middleware (Phase 2)** — Opt-in plugin `gina.plugins.Coep({ value })`. Settings: `coep.value` is one of three W3C HTML spec tokens (`"require-corp"`, `"credentialless"`, `"unsafe-none"`); default `"require-corp"` matches helmet. Required (paired with `Coop: same-origin` / #HDR13) to enable SharedArrayBuffer and high-resolution `performance.now()` in the page. Caller options always win over settings; values are normalised to lowercase. Mirrors the #HDR3 ReferrerPolicy single-enum shape with throw-on-invalid validation. The `require-corp` default BREAKS embeds without matching CORP/CORS headers — README walks users through the three escape hatches (set CORP via #HDR14, downgrade to `credentialless`, downgrade to `unsafe-none`). Idempotent — first-writer-wins. 56 unit tests. **First of the three Phase 2 cross-origin policies**; HDR13 Coop and HDR14 Corp to follow, then HDR15 SecurityHeaders combined wrapper closes Phase 2. | `0.4.0-alpha` | 2026-05-17 |
 | ✅ | **`Cross-Origin-Opener-Policy` (COOP) middleware (Phase 2)** — Opt-in plugin `gina.plugins.Coop({ value })`. Settings: `coop.value` is one of four W3C HTML spec tokens (`"same-origin"`, `"same-origin-allow-popups"`, `"noopener-allow-popups"`, `"unsafe-none"`); default `"same-origin"` matches helmet. Required (paired with `Coep: require-corp` / #HDR6) to enable cross-origin isolation. Same-origin isolates `window.opener` references on top-level navigation; same-origin-allow-popups is more compat-friendly for OAuth popup flows. The fourth token `noopener-allow-popups` (W3C spec addition, Chrome 119+/Firefox 131+) severs `window.opener` for popups even at same-origin while keeping the popup window open. Caller options always win over settings; values are normalised to lowercase. Mirrors the #HDR6 Coep single-enum shape. The `same-origin` default BREAKS OAuth popup flows where the popup needs to call back into the opener — README walks users through the three escape hatches. Idempotent — first-writer-wins. 61 unit tests. **Second of the three Phase 2 cross-origin policies**; HDR14 Corp follows, then HDR15 SecurityHeaders combined wrapper closes Phase 2. | `0.4.0-alpha` | 2026-05-17 |
 | ✅ | **`Cross-Origin-Resource-Policy` (CORP) middleware (Phase 2)** — Opt-in plugin `gina.plugins.Corp({ value })`. Settings: `corp.value` is one of three W3C HTML spec tokens (`"same-origin"`, `"same-site"`, `"cross-origin"`); default `"same-origin"` matches helmet's per-middleware default. Resource-side complement to #HDR6 Coep's `require-corp` enforcement — cross-origin embeds under `Coep: require-corp` require the embed-target bundle to set `Corp: cross-origin` (or wider) to load. Most restrictive practical default; defends against side-channel attacks that load a resource cross-origin to measure size/timing for fingerprinting. Caller options always win over settings; values are normalised to lowercase. Mirrors the #HDR6 Coep + #HDR13 Coop single-enum shape. The `same-origin` default BREAKS cross-origin embeds when the resource serves at a separate origin from the embedding page — README walks users through the three escape hatches (pick `same-site` for first-party multi-subdomain setups, pick `cross-origin` for publicly-embeddable CDN assets, per-bundle scoping where the page bundle keeps strict + the CDN bundle adopts `cross-origin`). Idempotent — first-writer-wins. 60 unit tests. **Third and final of the three Phase 2 cross-origin policies**; HDR15 SecurityHeaders combined wrapper follows as the closing slice. | `0.4.0-alpha` | 2026-05-17 |
 | ✅ | **`SecurityHeaders` combined wrapper (Phase 2 — closes #HDR + Phase 1.5 extension)** — Opt-in plugin `gina.plugins.SecurityHeaders({...})` composes the full HDR1-14 set in a single mount with one `settings.json` block (`securityHeaders.*`). **Batteries-included safe set**: calling `SecurityHeaders()` with no opts mounts the **12 non-footgun plugins** (xContentTypeOptions, xFrameOptions, referrerPolicy, hsts, originAgentCluster, hidePoweredBy, xDnsPrefetchControl, xXssProtection, xDownloadOptions, xPermittedCrossDomainPolicies, coop, corp) with per-plugin defaults. CSP (#HDR5) and COEP (#HDR6) are opt-in only (CSP throws on missing directives; COEP `require-corp` breaks embeds without CORP). Per-sub-config explicit opt-out via `<key>: false` or `null` (e.g. `SecurityHeaders({ hsts: false })` for HTTP-only bundles). Individual plugins remain mountable independently as power-user escape hatches — the idempotent first-writer-wins pattern means no double-emit when stacking. Mirrors helmet's `helmet()` orchestrator. **Originally shipped 2026-05-17 with 9 sub-plugins** (HDR1-7 + HDR5 + HDR6/13/14) closing Phase 2; **extended 2026-05-17 to 14 sub-plugins** when Phase 1.5 (HDR8-12) closed — wrapper safe-set grew from 7 to 12 plugins. 92 unit tests (was 83 + 9 for the HDR8-12 sub-config opt-out + override coverage). **Closes Phase 2 + Phase 1.5 extension.** | `0.4.0-alpha` | 2026-05-17 |
+| ✅ | **CSP per-response nonce (`useNonce`) (#HDR16)** — `gina.plugins.Csp({ directives, useNonce: true })` (opt-in, default `false`) generates a fresh `crypto.randomBytes(16).toString('base64')` nonce per response (128-bit W3C CSP3 floor), stamps it on the per-request carrier `req._ginaCspNonce`, and appends `'nonce-<value>'` to `script-src` (fallback `default-src`; the factory throws at call time if neither directive is present). The swig + nunjucks render delegates read `req._ginaCspNonce` and set a matching `nonce="<value>"` attribute on the framework-injected `onGinaLoaded` bootstrap `<script>`, letting a bundle drop `'unsafe-inline'` from `script-src` with no application template change. `useNonce: false` keeps the static-header fast-path (header computed once at factory time, no `req` slot) — zero behaviour change for bundles that don't opt in. The nonce is generated only when gina is the header writer (idempotent first-writer-wins via `res.getHeader`), so when an upstream proxy/ingress sets CSP, header and tags stay consistent. Carrier is `req._ginaCspNonce` (NOT `res.locals` — absent in both engines; NOT `process.gina.*` — process-global), mirroring the `req._ginaProxyPrefix` precedent. The dev-only Inspector (`__ginaData` + console-capture) and metrics-patch inline blocks are nonced via the same capture in both engines (nunjucks reads a stable `local._cspNonce` slot, not volatile `local.req`, per the #M1 discipline). A follow-up exposes the nonce to templates as `{{ page.cspNonce }}` (swig) / `{{ cspNonce }}` (nunjucks) — the **application-template nonce helper** — and nonces the dev-only Inspector `statusbar.html` `<script>` through that var (`<script{% if page.cspNonce %} nonce="{{ page.cspNonce }}"{% endif %}>`); bundles can mark their own inline scripts the same way. | `0.4.0-alpha` | 2026-05-27 |
 
 ---
 
@@ -203,7 +204,7 @@ New database connectors follow the same interface as the existing Couchbase conn
 | ✅ | **ScyllaDB** | `0.4.0` | Q4 2026 | Cassandra-compatible wide-column store. Client: `cassandra-driver` (Apache Software Foundation; Node.js has no first-party shard-aware driver — token-aware routing only). ORM connector + session store via CQL `USING TTL`. Implemented 2026-05-09 (#CN5). |
 | ✅ | **MongoDB** | `0.4.0` | Q4 2026 | Document store connector. Client: `mongodb` (official driver, `>=7.0.0`). ORM connector with `pipelines/<Entity>/*.json` files (JSON body + JSDoc-style `@param`/`@return` annotations + `{$arg: N}` positional placeholders + `{$oid: <hex>}` ObjectId literals + `$scope` substitution at load time). Session store backed by a TTL index (`createIndex({expiresAt: 1}, {expireAfterSeconds: 0})` auto-created on first `set()` with one-shot guard). `get()`/`length()`/`all()` filter on `expiresAt` to protect against MongoDB's 60s TTL monitor lag. Implemented 2026-05-09 (#CN6). |
 | ✅ | **Couchbase SDK v2 deprecation** | `0.2.0` | 2026-03-27 | Couchbase Server SDK v2 reached end-of-life in 2021. `connector.v2.js` now logs a deprecation warning at connection time, and a fatal error when V8 pointer compression is active (NAN bindings are incompatible). Upgrade path: set `sdk.version` to `3` or `4` in your bundle's `connectors.json`. |
-| 📋 | **Couchbase SDK v2 removal** | `0.4.0` | Q4 2026 | `connector.v2.js` and all `sdk.version <= 2` branches removed. Default falls back to v3 when `sdk.version` is unset. Full migration guide in `CHANGELOG.md`. |
+| ✅ | **Couchbase SDK v2 removal** | `0.4.0` | 2026-05-22 | `connector.v2.js` and `session-store.v2.js` removed, along with every `sdkVersion`-based v2 branch in `index.js` (consistency setup, prepared-statement builder, FTS substitution, query dispatch, and the `bulkInsert` path). The connector and session-store resolvers default to SDK v3 and fail fast with an explicit upgrade message when a project still pins `couchbase@2`. Migration is a driver bump (`npm install couchbase@^4`), not a `connectors.json` edit — `sdk.version` is derived from the installed `couchbase` npm major, never a config key. |
 | ✅ | **`peerDependencies` for connector clients** | `0.3.0` | 2026-04-01 | All connector client libraries (`ioredis`, `mysql2`, `pg`, `mongodb`, `@scylladb/scylla-driver`, `couchbase`, `openai`, `@anthropic-ai/sdk`) are declared as optional `peerDependencies`. Signals the tested version range to npm/yarn and surfaces a compatibility warning when a user pins an untested version. Zero framework runtime dependency — clients are always loaded from the project's `node_modules`. |
 | ✅ | **`connector:*` CLI group + lint/fix migration** | `0.3.8` | Q2 2026 | New CLI for managing `connectors.json` at project (shared) or bundle scope: `connector:list`, `connector:add`, `connector:rm`, `connector:migrate`. Positional-absence signals scope — omit `<bundle>` to operate on `shared/config/connectors.json`, include it to operate on the bundle's own. `list` cross-references declared connectors against the project's `node_modules` and prints install status per driver. `add` writes the JSON entry and prints the exact `npm install <driver>@<range>` command (no auto-install in v1). `rm` supports `--dry-run` / `--force` and scans sibling bundles for usage before removing at project scope. `migrate` lints every `connectors.json` (or a single bundle's file) and, with `--fix`, injects missing `$schema` entries while preserving comment headers and key order — dry-run by default. Framework-side auto-migrate hook deferred to `0.4.0` alongside the Couchbase SDK v2 removal where a concrete old-shape → new-shape delta will justify touching the boot path. Adds a `version` property to the `connectors.json` schema for install-version resolution. Optional follow-up: `--install` flag with lockfile-based package manager detection. **Session 1 (`connector:list`) shipped 2026-04-21, `0.3.7-alpha.3`** — read-only lister with overlay/override detection, driver install probing, version-pin disagreement warnings, JSON output, 89 source-inspection unit tests. **Session 2 (`connector:add` + schema `version`) shipped 2026-04-21, `0.3.7-alpha.3`** — writes shared or bundle-scoped connector entries, infers type from `<name>`, preserves comment headers and key order, pins `$schema` at the top, rejects overwrites without `--force`, prints `npm install <pkg>@"<range>"` install hint (AI resolves per protocol scheme, sqlite short-circuits to built-in note), adds `version` property to `schema/connectors.json`. 94 source-inspection unit tests; 7 live smoke tests. CLI flag rename (`--connector-port=`/`--driver-version=`) avoids framework-reserved `--port`/`--version`. **Session 3 (`connector:rm`) shipped 2026-04-21, `0.3.7-alpha.3`** — removes shared or bundle-scoped entries via positional-absence scoping (`remove` alias accepted); `--dry-run` previews without writing; `--force` skips the project-level usage guard that otherwise refuses when any bundle still references the same logical name; driver-retention hint prints after every removal naming sibling bundles that still use the same driver (sqlite exempt — built-in); inherited-from-shared hint fires when rm from a bundle targets an entry declared only in shared. Never runs `npm uninstall`. 81 source-inspection unit tests. **Session 4 (`connector:migrate`) shipped 2026-04-21, `0.3.7-alpha.3`** — CLI-only linter: dry-run by default, `--fix` applies auto-fixable issues in place. Two detection types: `missing-schema` (auto-fixable, injects `"$schema": "https://gina.io/schema/connectors.json"` pinned at top while preserving comment header and key order) and `bare-key-no-connector` (entry key not in `couchbase, mysql, postgresql, sqlite, redis, ai` enum with no `connector` field — warn-only since driver cannot be inferred). Two invocation modes via positional-absence: `@<project>` scans shared + every bundle; `<bundle> @<project>` scans just that bundle. `--format=json` emits `{project, scope, bundle, fixApplied, files[]}` envelope for CI. Registered as offline — no framework socket required. Idempotent. Never modifies `core/config.js` and never runs at bundle boot — explicit and opt-in. Real framework-side hook deferred to `0.4.0` alongside Couchbase SDK v2 removal. 87 source-inspection unit tests; full write-path smoke test on a disposable sandbox (shared + two bundles), plus a no-false-positive smoke on a real 7-bundle project. |
 
@@ -295,7 +296,7 @@ A cold audit of the Couchbase connector identified two critical security vulnera
 | --- | --- | --- | --- |
 | ✅ | **AI connector** — Declare any LLM provider in `connectors.json` via named protocol (`anthropic://`, `openai://`, `deepseek://`, `qwen://`, `groq://`, `mistral://`, `gemini://`, `xai://`, `perplexity://`, `ollama://`). Unified `.infer(messages, options)` normaliser + raw `.client` for advanced use. | `0.3.0` | Q1 2026 |
 | ✅ | **`renderStream` — streaming responses** — `self.renderStream(asyncIterable, contentType)` streams SSE or chunked JSON without buffering. Required for LLM token streaming without bypassing the render pipeline. | `0.3.0` | 2026-03-31 |
-| 📋 | **Async job pattern for slow AI calls** — First-class "start job → return jobId → poll or webhook on completion" pattern integrated with the cron/queue infrastructure. Prevents LLM latency (1–30s) from blocking the response pipeline. | `0.4.0` | Q4 2026 |
+| ✅ | **Async job pattern for slow AI calls** — First-class "start job → return jobId → poll or webhook on completion" pattern, backed by the `lib/job` primitive (`self.startJob` / `self.inferAsync`, always-on `/_gina/jobs/:id` polling, opt-in completion webhook). Prevents LLM latency (1–30s) from blocking the response pipeline. | `0.4.0` | 2026-05-22 |
 
 ### Phase 3 — AI agents can consume Gina apps
 
@@ -359,8 +360,8 @@ Gina's built-in per-bundle inspector. Phases 1–2 ship as an embedded SPA at `/
 | --- | --- | --- | --- |
 | 🔨 | **`services/src/inspector/` standalone bundle** — ~~Rename `services/src/toolbar/` to `services/src/inspector/`~~ (done). Inspector SPA as a standalone gina bundle on port 4101. Connects to bundles via authenticated WebSocket. The embedded SPA at `/_gina/inspector/` remains for quick dev-mode access. | `0.5.0` | Q1 2027 |
 | ✅ | **Agent endpoint — dev-mode SSE (`/_gina/agent`)** — Combined data + log SSE stream. CORS, server.js + server.isaac.js (HTTP/2), Inspector SPA `tryAgent()` with `?target=` param. Named events (`event: data`, `event: log`). Manual connect form on "No source" overlay. | `0.3.0` | 2026-04-05 |
-| 📋 | **Agent endpoint — production auth** — Upgrade `/_gina/agent` to authenticated WebSocket. API key gating (`inspector.agent_key` in `settings.json`), production-safe toggle. | `0.5.0` | Q1 2027 |
-| 📋 | **Toggleable instrumentation** — Runtime toggle for query instrumentation independent of `NODE_ENV_IS_DEV`. Enable in production for a time window without full dev mode. Minimal overhead when disabled. | `0.5.0` | Q1 2027 |
+| 🔨 | **Agent endpoint — production auth** — **Authenticated `/_gina/agent` + production-safe toggle shipped via the existing SSE transport** (opt-in `inspector.agent.enabled` + key in `settings.json`, constant-time compare, `${secret:KEY}`-capable; key via the `x-gina-inspector-key` header or a `?key=` query param; dev stays open + keyless). Authenticates remote server-log streaming outside dev mode. Remaining: WebSocket transport (deferred — only needed for bidirectional commands). | `0.5.0` | Q1 2027 |
+| 🔨 | **Toggleable instrumentation** — Runtime toggle for query + flow instrumentation independent of `NODE_ENV_IS_DEV`: a time-boxed, key-authenticated window (`POST /_gina/instrument`) runs capture in production over the authenticated `/_gina/agent` SSE, without full dev mode. Opt-in via `inspector.instrumentation`; 3600s hard cap with auto-revert. **v1 shipped 2026-05-26** (JSON/XHR + cross-bundle egress). Remaining: server-rendered HTML-page-render egress (follow-up). | `0.5.0` | Q1 2027 |
 | 📋 | **Multi-bundle dashboard** — Discover all running bundles via `ports.json`, connect to each agent. Full-stack request tracing across bundle boundaries. | post-1.0.0 | — |
 | 📋 | **Browser extension companion** — Chrome/Firefox DevTools panel. Thin UI shell connecting to the standalone Inspector via WebSocket. Optional — not a replacement. | post-1.0.0 | — |
 
@@ -383,7 +384,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.4.0` | 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` | 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

@@ -325,6 +325,7 @@ async function onExec() {
         'project:',
         'protocol:',
         'scheme:',
+        'secrets:',
         'service:',
         'view:',
         '--', //options or other aliases.

package/framework/v0.4.0/VERSION

@@ -0,0 +1 @@
+0.4.0

package/framework/{v0.3.16-alpha.1 → v0.4.0}/core/asset/plugin/dist/vendor/gina/html/statusbar.html

@@ -1,4 +1,4 @@
-<script>
+<script{% if page.cspNonce %} nonce="{{ page.cspNonce }}"{% endif %}>
 (function () {
     'use strict';
     var d = window.__ginaData;

package/framework/{v0.3.16-alpha.1 → v0.4.0}/core/asset/plugin/dist/vendor/gina/inspector/index.html

@@ -234,6 +234,7 @@
       <div class="bm-connect-sep"><span>or connect manually</span></div>
       <form id="bm-connect-form" class="bm-connect-form" autocomplete="off">
         <input id="bm-connect-url" type="text" placeholder="http://localhost:3100" spellcheck="false" aria-label="Bundle URL">
+        <input id="bm-connect-key" type="password" placeholder="inspector key (optional)" spellcheck="false" autocomplete="off" aria-label="Inspector key">
         <button type="submit" class="bm-btn bm-btn-accent">Connect</button>
       </form>
     </div>

package/framework/{v0.3.16-alpha.1 → v0.4.0}/core/asset/plugin/dist/vendor/gina/inspector/inspector.css

@@ -1108,11 +1108,29 @@ body {
   opacity: 0.65;
 }
 
+/* Server-emitted fallback value (the dimmed first half of a dual badge).
+   Italic + a slightly deeper dim so a value sourced from the server reads
+   distinctly from the client-measured primary AND from the engine-version
+   dim (.bm-vbadge-ver). Pure opacity + font-style — no color — keeps it
+   theme-safe (no [data-theme] mirror needed). */
+.bm-vbadge-svr {
+  opacity: 0.55;
+  font-style: italic;
+}
+
 .bm-vbadge-sep {
   margin: 0 1px;
   opacity: 0.4;
 }
 
+/* Engine version — dimmed, normal-case (overrides the uppercase + tracking
+   that `.bm-vbadge-engine` applies). */
+.bm-vbadge-engine .bm-vbadge-ver {
+  opacity: 0.65;
+  text-transform: none;
+  letter-spacing: 0;
+}
+
 /* Load — green tint */
 .bm-vbadge-load {
   color: var(--ok);
@@ -2522,6 +2540,11 @@ details[open] > summary.bm-summary::before {
   background: rgba(239, 83, 80, 0.12);
 }
 
+.bm-idx-uncovered {
+  color: #e6b800;
+  background: rgba(230, 184, 0, 0.12);
+}
+
 .bm-idx-na {
   color: var(--text-dim);
   opacity: 0.5;
@@ -2552,6 +2575,10 @@ details[open] > summary.bm-summary::before {
   color: #c62828;
   background: rgba(198, 40, 40, 0.1);
 }
+[data-theme=light] .bm-idx-uncovered {
+  color: #8a6d00;
+  background: rgba(138, 109, 0, 0.1);
+}
 [data-theme=light] .bm-idx-na {
   color: var(--text-dim);
   background: rgba(0, 0, 0, 0.05);
@@ -3613,5 +3640,3 @@ details[open] > summary.bm-summary::before {
     text-align: left;
   }
 }
-
-/*# sourceMappingURL=inspector.css.map */