gina 0.3.7-alpha.9 → 0.3.8

package/CHANGELOG.md

@@ -6,6 +6,20 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html),
 and is generated by [Changie](https://github.com/miniscruff/changie).
 
 
+## 0.3.8 - 2026-04-26
+### Fixed
+* Fixed `npm install -g gina` failing with `Cannot find module 'psl'` on fresh and upgrade installs (regression from 0.3.7). The pre/post-install scripts no longer load the framework `lib` registry — `psl` and `@rhinostone/swig` are now declared as top-level npm dependencies so the runtime resolves them via the standard module resolution chain, and a helpers pre-load in the install scripts ensures `lib/logger`'s circular load completes correctly so internal helpers' module-local `console` references bind to the full Logger singleton.
+
+## 0.3.7 - 2026-04-26
+### Added
+* Released `0.3.7` — cumulative stable of the `0.3.7-alpha.1` through `0.3.7-alpha.10` cycle. Headline tracks: **Web Security CSRF trilogy** (`gina.plugins.Session()` cookie hardening + `gina.plugins.Csrf()` signed double-submit token middleware + Origin/Referer pre-filter; OWASP ASVS 4.0 V4.2.1 aligned; opt-in plugin shape; per-route `csrfExempt: true` for webhook receivers). **Nunjucks template engine opt-in** (`render.engine = "nunjucks"` per bundle; filter parity #NJ1, setResources/asset injection #NJ2, render cache #NJ3, Early Hints 103 auto-send #NJ4). **MCP server** (`bundle:mcp` static manifest emit + `bundle:mcp-start` stdio and HTTP transports; #AI8 Phases 1/2a/2b). **Connector CLI** (`connector:list/add/rm/migrate`; #CN10). **Eval-safety hardening** (#SCS1 family — collection safe-evaluator + validator-plugin grammar-locked walker replacements; vendored-dep CVE-visibility invariant locked in via OSV scan workflow). Supply-chain trim (`psl` swap for vendored MPL-2.0 PSL data, `optimist` removal). Release-pipeline hardening (`gna.js` stable-version sync at framework-dir rename, StateStore + gina.db sync across renames, asset-plugin build honours `--gzip-bin`/`--brotli-bin` overrides). Plus `Session.name` drop-in identity restoration in alpha.10. See per-alpha sections for per-feature detail and test counts; full suite 3822/3822 at the stable cut.
+
+## 0.3.7-alpha.10 - 2026-04-26 (npm only — no git tag)
+### Fixed
+* `gina.plugins.Session()` no longer clobbers the wrapper's `Function.name` property. Bundles that introspect the wrapper (`require('gina').plugins.Session(require('express-session')).name`) now see `'session'` (matching upstream) instead of `'ginaSession'`. Achieved via a small refactor: the outer wrapper delegates to an inner `ginaSessionDispatch` named function, with `Object.defineProperty(wrapped, 'name', { value: expressSession.name, configurable: true })` overriding the outer `.name`. The inner `ginaSessionDispatch` frame stays visible in stack traces, so gina remains detectable for debugging while the public-facing identity is the upstream's. Static-surface preservation (`Store`, `MemoryStore`, `Session`, `Cookie`) and the SameSite=None invariant are unchanged. 2 new unit tests in `test/core/session-plugin.test.js` (drop-in identity assertion + stack-trace visibility lock). Full suite 3768/3768 (3766 baseline + 2 new). Surfaced from a freelancer/v3 session: "Gina's wrapper clobbering expressSession.name — is an upstream concern".
+### Security
+* `gina.plugins.Csrf()` now layers an Origin/Referer pre-filter ON TOP of the signed double-submit token verify (`#CSRF3`). On every mutating request (POST/PUT/PATCH/DELETE) the middleware reads `Origin` first, falls back to parsing the host out of `Referer` when `Origin` is absent (or is the literal `"null"` sentinel browsers send for sandboxed iframes), and matches the result against `settings.json > csrf.allowedOrigins`. Both headers missing → 403 `[csrf] forbidden — missing origin/referer`. Mismatch → 403 `[csrf] forbidden — origin not allowed`. The token verify only runs after the Origin check passes, so a forged token + matching cookie still gets rejected when the request didn't come from an allowed origin (token layer ≠ Origin layer). Per-route `csrfExempt: true` bypasses BOTH layers consistently. New `settings.json` key `csrf.allowedOrigins`: empty/unset defaults to `[bundleHostname]` (auto-derived from `conf[bundle][env].hostname` or composed from `server.scheme + host + server.port`); non-empty replaces the default with an explicit allowlist for multi-domain bundles. Entries are matched literally case-insensitive after parsing down to `scheme://host[:port]` — different scheme on the same host doesn't match (`http://example.com` ≠ `https://example.com`); different port doesn't match. Factory throws at startup when `csrf.allowedOrigins` is empty AND no bundle hostname can be resolved — error message points at both fixes. 54 new unit tests (parser helpers, allowlist precedence, behavioural matrix Origin × Referer × allowlist, scheme/port discrimination, `Origin: "null"` sentinel handling, negative-invariant lock that matching token + mismatching Origin still 403s, exempt interaction, source-inspection guards pinning the pre-filter ordering); full suite 3822/3822 (prior 3768 + 54). Closes the three-phase CSRF trilogy started by `#CSRF1` (cookie hardening, alpha.8) and `#CSRF2` (signed double-submit token, alpha.9).
+
 ## 0.3.7-alpha.9 - 2026-04-26 (npm only — no git tag)
 ### Added
 * Exposed gina.csrfToken and gina.csrfInput in swig template context (#CSRF2 follow-up). When a bundle has registered the Csrf plugin and req.csrfToken is set on the active request, controller.js > setOptions() now publishes two keys to the template data: gina.csrfToken (raw base64url string) and gina.csrfInput (pre-formatted <input type="hidden" name="<fieldName>" value="<token>"> HTML). Templates render the hidden input with either {{ gina.csrfInput | safe }} or the manual <input ... value="{{ gina.csrfToken }}"> form. The field name comes from settings.json > csrf.fieldName (default _csrf, matching the plugin) and is HTML-attribute-escaped defensively (& " < >) before interpolation. The token itself is base64url ([A-Za-z0-9_-]) by construction so it is interpolated verbatim — encoding it would break round-trip when the form is submitted. When req.csrfToken is absent (bundle has not adopted the plugin) neither key is set; templates can guard with {% if gina.csrfToken %}. 25 unit tests in test/core/controller-csrf-context.test.js cover the source-inspection guards, the missing/empty/non-string rejection, the configured-fieldName path, the four HTML-attribute escapes, and the negative invariant (no eval, no template-literal interpolation, no encoding of the token).

package/ROADMAP.md

@@ -28,6 +28,7 @@ This roadmap covers planned features, architectural improvements, new connectors
 | --- | --- | --- | --- |
 | ✅ | **Automatic version migration** — Upgrading or downgrading gina (e.g. `0.1.x → 0.2.0`, `0.5.x → 1.0.0`) automatically migrates `~/.gina/` config to the new version on first startup. Downgrade is free — old version data is never removed. | `0.1.8` | 2026-03-26 |
 | ✅ | **`watchers.json`** — First-class bundle config for file watchers. Declare watchers on config files with event-based notification (no polling). Foundation for the dev-mode hot-reload system. | `0.2.0` | 2026-03-29 |
+| 📋 | **i18n core** — Per-bundle message catalogs under `bundle/locales/<culture>.json` with a fallback chain (specific culture → base language → default). Server-side `t(key, [params], [culture])` global helper with parameter interpolation and CLDR pluralisation. Swig and Nunjucks filters with the same surface (`{{ "key"\|t }}`, `{{ "key"\|t({ name: x }) }}`). Per-request locale negotiation from URL prefix / cookie / `Accept-Language` / settings default. CLI: `gina i18n:scan` for missing-key coverage per culture, `i18n:add <culture>` to seed a new catalog, `i18n:export` / `i18n:import` for `.po` / `.csv` / `.json` round-trip with translators. Headless by design — the visual translation editor lands later as the first content feature in Beemaster (admin Phase 3). | `0.3.8` | Q2 2026 |
 | 📋 | **PWA scaffold** — `gina bundle:add` drops `manifest.json`, a service worker stub (`sw.js`), and the required `<meta>` / `<link>` tags into the bundle boilerplate. Zero runtime dependency. Enables Gina apps to be installed on mobile as PWAs without additional tooling. | `0.4.0` | Q4 2026 |
 | ✅ | **Per-bundle framework version** — Declare `"gina_version": "0.1.8"` on any bundle entry in `manifest.json` to pin that bundle to a specific installed framework version. The socket server continues running its own version; only the spawned bundle process uses the declared version. Validated against the tracked version list in `main.json` before start. `--gina-version=X.Y.Z` flag on `bundle:start` provides the same override without touching config files. | `0.3.0` | 2026-03-31 |
 | ✅ | **PATCH method** — `req.patch` populated with the parsed request body (JSON or form-encoded). `req.body` aliases `req.patch`. URI params merged. `"method": "PATCH"` valid in `routing.json`. Use PATCH for partial updates (only sent fields change) vs PUT which replaces the full resource. | `0.3.0` | 2026-03-31 |
@@ -137,13 +138,13 @@ Complete the removal of `eval` / `new Function` call sites from the published ta
 
 ## Web Security
 
-Cross-site request forgery protection. Three-phase defense-in-depth plan aligned with OWASP ASVS 4.0 V4.2.1; each phase shippable on its own. Cookie hardening shipped as an opt-in plugin in `0.3.7-alpha.8`; token middleware and Origin pre-filter still open.
+Cross-site request forgery protection. Three-phase defense-in-depth plan aligned with OWASP ASVS 4.0 V4.2.1; each phase shippable on its own. All three phases shipped: cookie hardening in `0.3.7-alpha.8`, signed double-submit token middleware in `0.3.7-alpha.9`, Origin/Referer pre-filter in `0.3.7-alpha.10`.
 
 | Status | Feature | Version | Target |
 | --- | --- | --- | --- |
 | ✅ | **Cookie hardening (baseline)** — Opt-in plugin `gina.plugins.Session` wraps `express-session` and injects `SameSite=Lax` + `HttpOnly` + `Secure=auto` defaults from `settings.json > session.cookie.{sameSite,httpOnly,secure}` into the cookie options before the middleware sees them. Bundle-supplied cookie options always win, so intentional configuration is preserved. Adoption is a one-line swap in the bundle bootstrap: `var session = require('gina').plugins.Session(require('express-session'))`. Browser-parity invariant enforced at factory call time: `SameSite=None` without `Secure` throws at bundle startup. Migration guide flags cross-site cookie-send bundles (rare — third-party OAuth embeds, iframe flows) that must set `sameSite: "none"` + `secure: true` explicitly. 41 unit tests (source-inspection guards + mergeCookie + invariant negative-lock + resolveSettingsDefaults + end-to-end through stub express-session + registration + template integrity). | `0.3.7-alpha.8` | 2026-04-24 |
 | ✅ | **Signed double-submit token middleware** — Stateless signed-double-submit-cookie pattern (OWASP ASVS 4.0 V4.2.1). Opt-in plugin `gina.plugins.Csrf()`: HMAC-SHA256 cookie bound to session ID + matching `X-Gina-CSRF-Token` header (or `_csrf` form field) required on POST/PUT/PATCH/DELETE; `timingSafeEqual` comparison; safe methods (GET/HEAD/OPTIONS) pass through. Per-route opt-out via `routing.json > "csrfExempt": true` for webhook receivers (Stripe, GitHub, etc.). Server secret read from `process.env.GINA_CSRF_SECRET` at factory-call time — no dev fallback. Sessionless or session-after-csrf misorder produces a clear `next(err)` message pointing at the fix. Stateless so it scales with distributed Redis/K8s sessions without server-side storage; signed so sibling subdomains cannot inject cookies. 69 unit tests (source-inspection guards, generateToken/verifyToken primitives, negative-invariant lock, issue + verify middlewares, per-route exempt, plugin registration, settings template integrity). Validator AJAX header injection + controller template context (`{{ gina.csrfToken }}` / `{{ gina.csrfInput \| safe }}`) ship in follow-up commits. | `0.3.7-alpha.9` | 2026-04-25 |
-| 📋 | **Origin/Referer pre-filter** — Secondary check on mutating methods, layered on top of the token middleware: `Origin` (or `Referer` fallback) must match the bundle's configured hostname or an explicit allowlist. Configured via `settings.json > csrf.allowedOrigins`. Belt-and-suspenders catching edge cases tokens might miss (referrer-header log leaks, legacy browser bugs, misconfigured reverse proxies). Performance: one string compare per mutating request. | `0.4.0` | Q4 2026 |
+| ✅ | **Origin/Referer pre-filter** — Secondary check on mutating methods, layered on top of the token middleware INSIDE `gina.plugins.Csrf()`: parses `Origin` first, falls back to the host portion of `Referer`, and matches against `settings.json > csrf.allowedOrigins`. Both headers missing → 403 `missing origin/referer`. Mismatch → 403 `origin not allowed`. Empty/unset `allowedOrigins` defaults to `[bundleHostname]` (auto-derived from `conf[bundle][env].hostname` or composed from `server.scheme + host + server.port`); non-empty = explicit allowlist for multi-domain bundles. Per-route `csrfExempt: true` bypasses BOTH Origin and token layers consistently. Negative-invariant lock: matching token + mismatching Origin still 403s — token layer ≠ Origin layer. Factory throws at startup when neither a settings allowlist nor a bundle hostname can be resolved. 54 unit tests added (parseRequestOrigin/parseOriginString helpers, resolveBundleHostname, resolveAllowedOrigins precedence, behavioural matrix Origin × Referer × allowlist, scheme/port discrimination, `Origin: "null"` sentinel handling, negative-invariant lock, exempt interaction, source-inspection guards pinning the pre-filter ordering). Full suite 3822/3822 (prior 3768 + 54). | `0.3.7-alpha.10` | 2026-04-26 |
 
 ---
 
@@ -286,7 +287,7 @@ Windows compatibility is a hard requirement for `1.0.0`. The alpha scope covers
 
 ## Inspector
 
-Gina's built-in per-bundle inspector. Phases 1–2 ship as an embedded SPA at `/_gina/inspector/` inside every bundle's own HTTP server (dev mode). Phase 3 evolves it into a standalone web app served by `services/src/inspector/` that can connect to any bundle in any environment — including production. Beemaster (global admin app) is a separate project.
+Gina's built-in per-bundle inspector. Phases 1–2 ship as an embedded SPA at `/_gina/inspector/` inside every bundle's own HTTP server (dev mode). Phase 3 evolves it into a standalone web app served by `services/src/inspector/` that can connect to any bundle in any environment — including production. Beemaster (global admin app) is a separate project — also the planned home for content-management surfaces such as the **i18n translation editor** (the visual layer of i18n core).
 
 **Why a standalone web app:** Electron is heavy and adds distribution burden. A browser extension is browser-specific and can't inspect from a different machine. The standalone web app works locally and remotely, any browser, zero install. A browser extension companion can be layered on top later.
 

package/framework/v0.3.8/VERSION

@@ -0,0 +1 @@
+0.3.8

package/framework/{v0.3.7-alpha.9 → v0.3.8}/core/plugins/lib/csrf/src/main.js

@@ -8,25 +8,33 @@
 'use strict';
 
 /**
- * Csrf plugin (#CSRF2) — signed double-submit token middleware.
+ * Csrf plugin (#CSRF2 / #CSRF3) — signed double-submit token middleware
+ * with an Origin/Referer pre-filter.
  *
- * Stateless CSRF defense aligned with OWASP ASVS 4.0 V4.2.1. Issues a
- * signed token cookie on safe-method requests and verifies a matching
- * value on mutating requests (POST/PUT/PATCH/DELETE). Token shape:
+ * Stateless CSRF defense aligned with OWASP ASVS 4.0 V4.2.1. On mutating
+ * methods (POST/PUT/PATCH/DELETE) the middleware now layers two checks:
  *
- *     <nonce_b64url>.<mac_b64url>
- *     mac = HMAC-SHA256(sessionId + ':' + nonce_b64url, GINA_CSRF_SECRET)
+ *   1. #CSRF3 — Origin/Referer pre-filter. Reads `Origin` first, falls
+ *      back to parsing the host out of `Referer`. Both missing → 403.
+ *      Mismatch against `csrf.allowedOrigins` → 403. Belt-and-suspenders
+ *      that catches edge cases tokens might miss (referrer-header log
+ *      leaks, legacy browser bugs, misconfigured reverse proxies).
+ *   2. #CSRF2 — signed double-submit token verify. Token shape:
  *
- * Bundles adopt it with two lines in their bootstrap, AFTER the session
- * middleware:
+ *          <nonce_b64url>.<mac_b64url>
+ *          mac = HMAC-SHA256(sessionId + ':' + nonce_b64url, GINA_CSRF_SECRET)
+ *
+ * Safe methods (GET/HEAD/OPTIONS) issue a fresh token cookie and pass
+ * through. Per-route opt-out via `routing.json > "csrfExempt": true`
+ * bypasses both layers (consistent across token + Origin checks).
+ *
+ * Bundles adopt the plugin with two lines in their bootstrap, AFTER the
+ * session middleware:
  *
  *     var csrf = require('gina').plugins.Csrf();
  *     app.use(session({...}));   // must register session FIRST
  *     app.use(csrf);
  *
- * Per-route opt-out via `routing.json > "csrfExempt": true` for webhook
- * receivers (Stripe, GitHub, etc.) where CSRF defense doesn't apply.
- *
  * @module plugins/csrf
  */
 
@@ -48,18 +56,20 @@ var MAC_BYTES   = 32;
  * the merged framework defaults.
  *
  * @returns {{cookieName: string, headerName: string, fieldName: string,
- *            rotate: string, safeMethods: string[]}}
+ *            rotate: string, safeMethods: string[],
+ *            allowedOrigins: string[]|null}}
  * @throws  {Error} when a setting has an unsupported value.
  * @inner
  * @private
  */
 function resolveSettingsDefaults() {
     var defaults = {
-        cookieName:  DEFAULT_COOKIE_NAME,
-        headerName:  DEFAULT_HEADER_NAME,
-        fieldName:   DEFAULT_FIELD_NAME,
-        rotate:      DEFAULT_ROTATE,
-        safeMethods: DEFAULT_SAFE_METHODS.slice()
+        cookieName:     DEFAULT_COOKIE_NAME,
+        headerName:     DEFAULT_HEADER_NAME,
+        fieldName:      DEFAULT_FIELD_NAME,
+        rotate:         DEFAULT_ROTATE,
+        safeMethods:    DEFAULT_SAFE_METHODS.slice(),
+        allowedOrigins: null
     };
     var csrfConf = {};
 
@@ -101,10 +111,134 @@ function resolveSettingsDefaults() {
             return String(m).toUpperCase();
         });
     }
+    if (Array.isArray(csrfConf.allowedOrigins)) {
+        defaults.allowedOrigins = csrfConf.allowedOrigins
+            .filter(function (o) { return typeof o === 'string' && o; })
+            .map(function (o) { return o.toLowerCase(); });
+    }
 
     return defaults;
 }
 
+/**
+ * Extract `scheme://host[:port]` from a URL-like string. Returns `null`
+ * for `"null"` (sandboxed-iframe sentinel), empty input, or anything
+ * that doesn't have a parseable scheme + authority.
+ *
+ * @param   {string} s
+ * @returns {string|null}
+ * @inner
+ * @private
+ */
+function parseOriginString(s) {
+    if (typeof s !== 'string' || !s) return null;
+    if (s === 'null') return null; // browsers send literal "null" for sandboxed iframes
+    var m = /^([a-z][a-z0-9+.\-]*):\/\/([^\/?#]+)/i.exec(s);
+    if (!m) return null;
+    return (m[1] + '://' + m[2]).toLowerCase();
+}
+
+/**
+ * Best-effort detection of the origin a request was issued from. Reads
+ * `Origin` first; falls back to parsing the host out of `Referer` when
+ * `Origin` is missing (rare — some same-origin legacy browsers strip
+ * `Origin` on safe-then-mutating sequences).
+ *
+ * @param   {object} req
+ * @returns {string|null}    `"scheme://host[:port]"` or null
+ * @inner
+ * @private
+ */
+function parseRequestOrigin(req) {
+    if (!req || !req.headers) return null;
+    var origin = parseOriginString(req.headers.origin);
+    if (origin) return origin;
+    var referer = req.headers.referer || req.headers.referrer;
+    return parseOriginString(referer);
+}
+
+/**
+ * Resolve the bundle's configured origin from the active runtime
+ * configuration. Tries `conf[bundle][env].hostname` first (a full URL
+ * the framework resolves at startup), then composes one from
+ * `server.scheme + '://' + host + ':' + server.port`. Returns `null`
+ * when neither shape is present (e.g. test stub without a host).
+ *
+ * @returns {string|null}
+ * @inner
+ * @private
+ */
+function resolveBundleHostname() {
+    try {
+        var ctx    = getContext();
+        var bundle = ctx && ctx.bundle;
+        var env    = ctx && ctx.env;
+        var conf   = (typeof getConfig === 'function') ? getConfig() : null;
+        if (!bundle || !env || !conf || !conf[bundle] || !conf[bundle][env]) {
+            return null;
+        }
+        var bc = conf[bundle][env];
+        if (typeof bc.hostname === 'string' && bc.hostname) {
+            return parseOriginString(bc.hostname) || bc.hostname.toLowerCase();
+        }
+        if (bc.server
+            && typeof bc.server.scheme === 'string' && bc.server.scheme
+            && typeof bc.host          === 'string' && bc.host
+            && (bc.server.port || bc.server.port === 0)) {
+            return (bc.server.scheme + '://' + bc.host + ':' + bc.server.port).toLowerCase();
+        }
+    } catch (ignored) {
+        return null;
+    }
+    return null;
+}
+
+/**
+ * Compute the allowlist for the Origin pre-filter. Precedence:
+ *   1. `opts.allowedOrigins` (factory override, test harness)
+ *   2. `settings.json > csrf.allowedOrigins`
+ *   3. `[ resolveBundleHostname() ]` — the bundle's configured origin
+ *
+ * Returns an array of lowercase `scheme://host[:port]` strings. Throws
+ * at factory time when the resolved list ends up empty — that means
+ * neither the user nor the framework could supply a hostname, and
+ * letting the middleware run would 403 every mutating request.
+ *
+ * @param   {string[]|null} fromOpts      — `opts.allowedOrigins`
+ * @param   {string[]|null} fromSettings  — `settings.csrf.allowedOrigins`
+ * @returns {string[]}
+ * @throws  {Error} when no origin can be resolved.
+ * @inner
+ * @private
+ */
+function resolveAllowedOrigins(fromOpts, fromSettings) {
+    var list = null;
+    if (Array.isArray(fromOpts) && fromOpts.length > 0) {
+        list = fromOpts;
+    } else if (Array.isArray(fromSettings) && fromSettings.length > 0) {
+        list = fromSettings;
+    } else {
+        var bundleHost = resolveBundleHostname();
+        list = bundleHost ? [bundleHost] : [];
+    }
+
+    list = list
+        .filter(function (o) { return typeof o === 'string' && o; })
+        .map(function (o) {
+            var parsed = parseOriginString(o);
+            return parsed || o.toLowerCase();
+        });
+
+    if (list.length === 0) {
+        throw new Error(
+            '[gina csrf] csrf.allowedOrigins is empty and the bundle hostname could not be'
+            + ' resolved from getConfig(). Set settings.json > csrf.allowedOrigins'
+            + ' (e.g. ["https://example.com"]) or pass {allowedOrigins:[...]} to Csrf().'
+        );
+    }
+    return list;
+}
+
 /**
  * 16 cryptographically secure random bytes.
  *
@@ -313,8 +447,13 @@ var SESSIONLESS_MESSAGE =
  * @param   {string} [opts.fieldName]
  * @param   {string} [opts.rotate]      — `"per-session"` (default) or `"per-request"`
  * @param   {string[]} [opts.safeMethods]
+ * @param   {string[]} [opts.allowedOrigins] — #CSRF3 allowlist of origins that may
+ *                                             issue mutating requests. Defaults to
+ *                                             `settings.json > csrf.allowedOrigins`,
+ *                                             which itself defaults to the bundle's
+ *                                             configured hostname.
  * @returns {function}                  — Express-compatible middleware `(req, res, next)`
- * @throws  {Error} when `GINA_CSRF_SECRET` is missing.
+ * @throws  {Error} when `GINA_CSRF_SECRET` is missing or no origin can be resolved.
  */
 function Csrf(opts) {
     opts = opts || {};
@@ -346,6 +485,10 @@ function Csrf(opts) {
                       ? opts.safeMethods.map(function (m) { return String(m).toUpperCase(); })
                       : defaults.safeMethods;
 
+    // #CSRF3 — Origin/Referer allowlist. Resolved once at factory time;
+    // throws if no usable origin can be resolved.
+    var allowedOrigins = resolveAllowedOrigins(opts.allowedOrigins, defaults.allowedOrigins);
+
     var headerNameLower = headerName.toLowerCase();
 
     return function ginaCsrf(req, res, next) {
@@ -382,6 +525,17 @@ function Csrf(opts) {
             return next();
         }
 
+        // #CSRF3 — Origin/Referer pre-filter. Layered ON TOP of the token
+        // check below: a forged token with a matching cookie still gets
+        // rejected here when the request didn't come from an allowed origin.
+        var requestOrigin = parseRequestOrigin(req);
+        if (!requestOrigin) {
+            return reject(req, res, 'missing origin/referer');
+        }
+        if (allowedOrigins.indexOf(requestOrigin) < 0) {
+            return reject(req, res, 'origin not allowed');
+        }
+
         var presented = readPresentedToken(req, headerNameLower, fieldName);
         var cookie    = readCookie(req, cookieName);
 
@@ -418,6 +572,10 @@ Csrf._readCookie              = readCookie;
 Csrf._appendSetCookie         = appendSetCookie;
 Csrf._isSecureRequest         = isSecureRequest;
 Csrf._readPresentedToken      = readPresentedToken;
+Csrf._parseOriginString       = parseOriginString;       // #CSRF3
+Csrf._parseRequestOrigin      = parseRequestOrigin;      // #CSRF3
+Csrf._resolveBundleHostname   = resolveBundleHostname;   // #CSRF3
+Csrf._resolveAllowedOrigins   = resolveAllowedOrigins;   // #CSRF3
 Csrf._ALLOWED_ROTATE          = ALLOWED_ROTATE;
 Csrf._SESSIONLESS_MESSAGE     = SESSIONLESS_MESSAGE;
 Csrf._NONCE_BYTES             = NONCE_BYTES;

package/framework/{v0.3.7-alpha.9 → v0.3.8}/core/plugins/lib/session/src/main.js

@@ -161,13 +161,25 @@ function Session(expressSession) {
         );
     }
 
-    var wrapped = function ginaSession(options) {
+    function ginaSessionDispatch(options) {
         options = options || {};
         var defaults = resolveSettingsDefaults();
         options.cookie = mergeCookie(options.cookie, defaults);
         assertInvariant(options.cookie);
         return expressSession(options);
-    };
+    }
+
+    var wrapped = function (options) { return ginaSessionDispatch(options); };
+
+    // Drop-in identity: introspection (`session.name`) returns the upstream
+    // identity (`'session'`), while gina stays visible in stack traces via
+    // the inner `ginaSessionDispatch` frame. Without this, freelancer/v3 and
+    // other bundles that sniff `session.name === 'session'` saw `'ginaSession'`
+    // — the wrapper was clobbering the upstream identity.
+    Object.defineProperty(wrapped, 'name', {
+        value: expressSession.name,
+        configurable: true
+    });
 
     // Preserve express-session's static surface (.Store, .MemoryStore,
     // .Session, .Cookie). Consumers do `var MemoryStore = session.MemoryStore`

package/framework/{v0.3.7-alpha.9 → v0.3.8}/core/template/conf/settings.json

@@ -82,20 +82,27 @@
       "secure": "auto"
     }
   },
-  // #CSRF2 — signed double-submit token middleware applied by gina.plugins.Csrf().
-  // The secret lives in `process.env.GINA_CSRF_SECRET` (NOT in this file) — generate
-  // with `openssl rand -base64 64` and store in env.json or your shell profile.
-  //   cookieName  — cookie name issued on safe methods
-  //   headerName  — request header read on mutating methods
-  //   fieldName   — form field read on mutating methods
-  //   rotate      — "per-session" (default) or "per-request"
-  //   safeMethods — methods that issue without verifying (default GET/HEAD/OPTIONS)
+  // #CSRF2 / #CSRF3 — signed double-submit token middleware + Origin/Referer
+  // pre-filter applied by gina.plugins.Csrf(). The secret lives in
+  // `process.env.GINA_CSRF_SECRET` (NOT in this file) — generate with
+  // `openssl rand -base64 64` and store in env.json or your shell profile.
+  //   cookieName     — cookie name issued on safe methods
+  //   headerName     — request header read on mutating methods
+  //   fieldName      — form field read on mutating methods
+  //   rotate         — "per-session" (default) or "per-request"
+  //   safeMethods    — methods that issue without verifying (default GET/HEAD/OPTIONS)
+  //   allowedOrigins — #CSRF3 allowlist matched against the request `Origin` header
+  //                    (or `Referer` host fallback) on mutating methods.
+  //                    Empty/unset = bundle's configured hostname only;
+  //                    non-empty = explicit allowlist (multi-domain bundles).
+  //                    Format: ["https://example.com", "https://www.example.com"].
   "csrf": {
     "cookieName": "gina-csrf-token",
     "headerName": "X-Gina-CSRF-Token",
     "fieldName": "_csrf",
     "rotate": "per-session",
-    "safeMethods": ["GET", "HEAD", "OPTIONS"]
+    "safeMethods": ["GET", "HEAD", "OPTIONS"],
+    "allowedOrigins": []
   },
   "engine.io": {
     // Reserved Gina infrastructure range: 4100–4199

package/framework/{v0.3.7-alpha.9 → v0.3.8}/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gina-framework",
-  "version": "0.3.7-alpha.9",
+  "version": "0.3.7",
   "dependencies": {
     "@rhinostone/swig": "^1.6.0",
     "psl": "^1.15.0"

package/gna.js

@@ -15,14 +15,14 @@
 'use strict';
 
 // Framework core — the main gna module (lifecycle hooks, lib, etc.)
-var _gna = require('./framework/v0.3.7-alpha.9/core/gna');
+var _gna = require('./framework/v0.3.8/core/gna');
 
 // SuperController and EntitySuper — loaded from their source modules
-var SuperController = require('./framework/v0.3.7-alpha.9/core/controller');
-var EntitySuper     = require('./framework/v0.3.7-alpha.9/core/model/entity');
+var SuperController = require('./framework/v0.3.8/core/controller');
+var EntitySuper     = require('./framework/v0.3.8/core/model/entity');
 
 // uuid — from the lib registry
-var uuid = require('./framework/v0.3.7-alpha.9/lib/uuid');
+var uuid = require('./framework/v0.3.8/lib/uuid');
 
 module.exports = {
 

package/llms.txt

@@ -858,3 +858,15 @@ YAML indent trap: the heredoc body and the `EOF` terminator must land at column
 74. **Vendored-dep `package.json` metadata carries CVE-visibility — never strip `dependencies`.** Supersedes #73's "strip" fix pattern. Vendored deps under `framework/v*/core/deps/` are supply-chain surface identical to npm-installed deps: Socket, Dependabot, and `npm audit` all read the sub-`package.json` files inside the published tarball, extract `(name, version)` pairs, follow `dependencies` edges, and match each against their CVE databases. Stripping `dependencies` (or `devDependencies`, or `scripts`) to "reduce Socket's dep count" removes that signal — even when the fields are "dead at runtime" because the vendored code resolves sibling deps via relative-path `require()`. The metadata is load-bearing for security tooling. **The invariant**: vendored `package.json` stays byte-identical to the upstream npm tarball until a local patch is applied. No strips, no reorders, no cleanups. **Patch discipline**: when gina needs to modify a vendored dep's source, bump its `version` from `<upstream>` to `<upstream>-rhinostone.N` (e.g. `1.6.0-rhinostone.1`). Semver-compliant (it's a prerelease identifier), so OSV/Socket/Dependabot's range-matching still hits the base upstream CVE record; the suffix is a read-the-tree-and-know-at-a-glance signal that the copy has diverged. Reset the counter on any upstream version bump. **Belt-and-suspenders**: `.github/workflows/vendored-cve.yml` runs a Node script (`.github/scripts/scan-vendored-cves.js`) on every push + weekly Sunday cron that walks `framework/v*/core/deps/*/package.json`, queries `api.osv.dev/v1/query` for each `(name, version)` pair (normalising away the `-rhinostone.N` suffix before querying), and fails the build on any matched vulnerability. Independent of whichever third-party scanner happens to be active on the published tarball — if Socket/Dependabot ever shifts methodology again, CVE coverage on vendored deps is still guaranteed locally. **Precedent**: `gina@0.3.7-alpha.5` stripped the vendored metadata per #73's (incorrect) advice — flagged the same day by a maintainer concern that `core/deps/` was no longer being scanned. Reverted in alpha.6 (commit `e5d5d0a2`) along with `.github/workflows/vendored-cve.yml` + `.claude/architecture/vendored-deps.md` documenting the discipline. Socket count went from 3 back to 4 (streamsearch edge restored); every entry is a truthful dep the scanners SHOULD see. **Key reframe**: supply-chain surface is not dep-count minimization — it's whether the scanners have the signal they need. An accurate count with CVE visibility beats an under-reported count with blind spots every time.
 
 77. **Session cookies in gina are NOT framework-owned — they are issued by the bundle's own `app.use(session({...}))` call via `express-session`, so framework-level cookie hardening cannot be transparent without regressing intentional bundle choices.** The framework's `lib.SessionStore(session)` factory is a thin wrapper that receives the bundle's `express-session` module reference, reads `connectors.json[session.name].connector`, and returns a connector-specific Store class. It never holds a reference to the cookie options, and it runs once per bundle boot — long after the bundle's `index.js` has already captured `var session = require('express-session')` as a local. Nothing in `core/server.js`, `core/server.isaac.js`, or `core/server.express.js` writes `Set-Cookie` — those three files have zero grep matches on `cookie` and `set-cookie`. **Chokepoint analysis trap**: the single shared response entry at `core/server.js:2324` (`self.instance.all('*', function onInstance(request, response, next) { ... })`) does look like the natural place to wrap `response.setHeader` to post-process every `Set-Cookie` value, and Isaac + Express both route through it. But Set-Cookie strings carry no provenance: `Set-Cookie: sessionid=abc; Path=/; Secure` could be a bundle that never thought about `HttpOnly` (safe to add) OR a bundle that explicitly set `httpOnly: false` because a client-side validator or toolbar has to read `document.cookie` (adding `HttpOnly` breaks it). Inspecting three real bundles (`~/Sites/freelancer/v3/src/{auth,dashboard,public}/index.js`) showed all three deliberately set `httpOnly: false` and comment out `sameSite` — a transparent wrap would have silently regressed every one. This is exactly the failure mode CLAUDE.md's "Don't strip what you haven't surveyed" rule warns about, in its dual form: "don't ADD what the source didn't ask for either". **The correct shape for a cookie-hardening feature** is an opt-in plugin at `core/plugins/lib/session/src/main.js` that wraps `expressSession(options)` with a factory: reads `settings.json > session.cookie.{sameSite, httpOnly, secure}`, merges defaults into `options.cookie` only for flags the caller did NOT set (guarded by `Object.prototype.hasOwnProperty.call(caller, key)`), validates the browser-parity invariant (`SameSite=None` without `Secure` throws), and passes through. Adoption is a one-line swap in the bundle bootstrap: `var session = require('gina').plugins.Session(require('express-session'))`. Existing bundles that don't adopt continue working exactly as before; adopting is explicit and visible in the diff. **The measurement step that surfaced the trap**: before writing any code, grep real bundle code for cookie flag patterns — `grep -nE 'httpOnly|sameSite|secure[\s:]' ~/Sites/<project>/src/*/index.js`. If any bundle has deliberate `httpOnly: false` or `sameSite` commented out, transparent wrapping is off the table and the feature must be opt-in. Precedent: #CSRF1 (2026-04-24, shipped in `0.3.7-alpha.8`) — initial design pivoted from per-request `response.setHeader` wrap to opt-in `gina.plugins.Session` plugin after the Freelancer measurement showed three bundles with deliberate `httpOnly: false`. The plugin shape also becomes the natural seam for #CSRF2 (signed double-submit token middleware, planned for `0.3.8`), which needs a session-aware injection point — session hardening and CSRF token plumbing share the same mount scope.
+
+78. **`git filter-repo` operational gotchas — second-run prompts, origin removal, committer-date SHA churn, and the local-only-tag false positive that makes a previously-cleaned repo *look* like it still has leaks.** Four traps in order: (1) **prior-run safety prompt** — if `.git/filter-repo/already_ran` exists from an earlier rewrite, the next run prints "Treat this run as a continuation of filtering in the previous run (Y/N)?" and reads stdin. `--force` does not bypass it. Pipe `echo Y |` for non-interactive runs. (2) **origin removed** — filter-repo deletes the `origin` remote at the end of every run by design ("so you don't accidentally push the rewritten history"). After the rewrite, `git remote add origin https://github.com/<owner>/<repo>.git` before any push. (3) **committer-date SHA churn** — filter-repo updates committer dates to "now" on every commit it walks, even when message and tree are unchanged. Every reachable commit gets a new SHA. Net effect: a no-op rewrite of an already-clean branch still produces a force-push divergence between local and origin. (4) **local-only-tag false positive** — `git log --all` reaches every ref, including local-only safety-net tags created by prior rewrites (`pre-rewrite-*-DATE`, `pre-history-scrub-*-DATE`). Those tags preserve un-substituted commits as personal backups. They are NOT on origin (verify with `git ls-remote origin 'refs/tags/pre-*'`) and therefore not violating the public-surface rule. Before re-running filter-repo on a previously-cleaned repo, check leak counts per branch with `git log <ref> --format='%s%n%b' | grep -iE '<patterns>' | wc -l` for each live branch individually — if all are zero, the live branches are clean and the only "leaks" left are in personal local-only tags that don't need rewriting. Precedent: 2026-04-25 second-pass leak scrub on gina-io/gina — comprehensive `git log --all` audit found 4 commit subjects + 3 commit bodies with descriptive feature mentions, but per-branch checks showed origin develop/master/dev/wip all already at 0 leaks. The remaining matches lived only in `pre-rewrite-*-20260421T233346Z` tags from a 2026-04-21 prior filter-repo. Today's filter-repo did push develop and dev/wip with cosmetically-different SHAs (force-pushed for nothing) before the per-branch verification surfaced that master was already clean. The reflex "saw leaks via `git log --all`, run filter-repo" needs the per-branch refinement step to avoid unnecessary force-push churn on tracking clones.
+
+79. **GitHub branch protection — `allow_force_pushes: false` blocks ALL force-pushes including admin (independent of `enforce_admins`); the dedicated subfield REST endpoint for this flag does not exist.** Two non-obvious behaviors: (1) **flag interaction** — `enforce_admins: false` does NOT mean admins can force-push when `allow_force_pushes: false`. The two flags work on different rule categories: `enforce_admins` controls whether review-style protections (required reviews, status checks) apply to admin actors; `allow_force_pushes` is a flat protocol-level block on history rewriting that GitHub's git backend rejects regardless of admin status. So `enforce_admins: false` + `allow_force_pushes: false` means: admins can merge without review, but cannot force-push. To force-push to a protected branch as admin, `allow_force_pushes` must be flipped to `true` (temporarily) before the push, then back to `false` after. (2) **subfield endpoint absence** — GitHub's REST API documents per-subfield endpoints for some protection flags (`POST/DELETE /repos/.../protection/required_signatures`, `enforce_admins`), but `POST /repos/.../protection/allow_force_pushes` and `DELETE /repos/.../protection/allow_force_pushes` both return `404 Not Found`. The subfield API is partial. To toggle `allow_force_pushes`, use either the full `PUT /repos/.../protection` payload (with all required fields including `required_status_checks`, `enforce_admins`, `required_pull_request_reviews`, `restrictions` — null for those without rules), or `DELETE /repos/.../protection` to drop protection entirely then re-`PUT` to recreate. The web UI Settings → Branches → "Allow force pushes" toggle is also a clean path when an admin is at the keyboard. **Best non-destructive workflow** when force-push is needed for a one-off operation: have an admin lift via web UI → push → admin re-enables. The API path is brittle (the full-PUT payload must be reconstructed exactly to avoid losing other rule settings). Precedent: 2026-04-25 leak scrub — attempted `gh api -X POST repos/gina-io/gina/branches/master/protection/allow_force_pushes` to allow a force-push of master, got 404 (subfield endpoint absent), the push correctly failed, no protection state was modified (verified after via `gh api .../protection --jq`). The 404 was harmless — neither flip happened — but the master push didn't go through either. master turned out to already be clean from the prior rewrite, so no push was actually needed. **2026-04-26 update (gina@0.3.7 stable cut, master-reset session)** — UI toggle did NOT take effect. Two attempts via Settings → Branches → "Allow force pushes" → Save left the underlying state unchanged (force-push still rejected with `GH006: Protected branch update failed`). Classic protection settings looked normal; rulesets API was empty (no competing rule). API-fallback PUT (full payload, `allow_force_pushes: true`) worked first try; flipped back after the push. Possible causes: stale browser session, Org-level enforcement, UI bug. **Refined pattern**: if the UI doesn't take effect after one attempt (verify immediately with `gh api repos/<owner>/<repo>/branches/<branch>/protection --jq .allow_force_pushes.enabled`), fall back to API-PUT — don't retry the UI. Saves a round-trip on a class of failure that's hard to diagnose at the UI layer.
+
+80. **Plan-vs-shipped attribute drift — when a multi-commit feature plan declares an interface attribute name, the shipped implementation may diverge, and downstream commits silently propagate the wrong name unless every fresh session re-grounds against the source.** The trap: a planning document or upstream commit prompt declares an interface attribute (e.g. "the plugin attaches the token to `req._csrfToken`"). The actual implementation, once written, names it differently (`req.csrfToken` — no underscore). Downstream commits that depend on the attribute (controller exposing it to template context, validator AJAX reading it off `req`, tests asserting on the name) all reference the original planned name unless their author re-verifies. The plan looks coherent; the code drifts. **Detection pattern**: every fresh agent session implementing a downstream commit must `grep -n '<attribute>' <upstream-source-file>` before referencing the attribute. If the plan and the source disagree, the source wins — re-read the plan, fix the references, flag the upstream-plan inconsistency in the session report so the planner can correct future-downstream prompts. **The source of truth for an in-flight feature is the shipped code on `develop`, not the upstream plan or prompt.** Plans rot the moment implementation deviates; planning hygiene means re-grounding every multi-commit feature against the latest develop tip before downstream work. Precedent: 2026-04-25 #CSRF2 implementation — the plan-of-record (commit-3 prompt) said `req._csrfToken`; commit-1's plugin attached `req.csrfToken` (verified at `core/plugins/lib/csrf/src/main.js:377,407`). The fresh agent for commit 3 caught it via the grep pattern and used the correct name, preventing silent wrong-attribute propagation into controller.js + 25 new tests + the planned docs guide.
+
+81. **CI flake-vs-regression triage — when a CI run fails on a commit, look for a same-message-different-SHA pair before assuming the code is buggy.** Rebases or amends produce two commits with identical messages but different SHAs. If `gh run list --repo <owner>/<repo> --branch <branch> --limit 10 --json databaseId,conclusion,headSha,name,displayTitle` shows the earlier SHA passed Tests and the later SHA failed, run `git diff --stat A..B` between them — empty output proves byte-identical content. Same content + different CI outcome = environmental flake, not regression, and the test should not be touched (per the "Don't change existing tests unless asked" rule). **Reproduce shape matters**: a single-file local run (`node --test test/lib/<file>.test.js`) is necessary but not sufficient — CI invokes all four directories in one process (`node --test test/core/*.test.js test/lib/*.test.js test/bin/*.test.js test/integration/helper.test.js`), and module / parallelism state shape differs between the two. Reproduce with the **exact CI invocation** before falling back to a rerun. **Cheapest discriminator order**: (1) `git diff --stat` between same-message SHAs (proves content-identical, ~1 second); (2) full-suite local invocation with the exact CI command (proves logic-deterministic at scale, ~30s); (3) `gh run rerun <id> --repo <owner>/<repo>` if (1)+(2) survive — green retry confirms environmental flake, red retry escalates to CI-environment investigation (Node version drift, runner timing, fixture pollution across the parallel file dispatch). **Watchlist hygiene**: log single-occurrence flakes to a local post-mortem journal under "CI flake watchlist" — `gh run list` retention defaults to 90 days, so without a local note a recurrence in 6 months looks like a first occurrence. Two occurrences of the same flake on a deterministic in-memory test = pattern, not coincidence. Precedent: 2026-04-26 — `test/lib/collection.test.js > 05 - delete > delete: Hotel without ids WHERE country = France` flaked once on run #24938620953 (`d1ea0a72`, 2026-04-25, Node 24.14.1, Ubuntu); same-content earlier SHA `623e4232` had passed; full-suite local run was 3766/3766 clean; rerun went green. Watchlist entry filed in the local post-mortem journal.
+
+82. **Source-inspection tests that assert source order — `src.indexOf('<funcName>(<args>)')` matches the function DEFINITION before the call site, not the call site.** When a test asserts "A must be called before B" via `indexOf` on a function-name-with-args fragment, the match lands on the `function <funcName>(<args>)` definition near the top of the file, not the call site lower in the body. If both names are defined in the same source-order as their call sites, the assertion accidentally passes for the wrong reason; if they're defined in a different order than they're called (helper defined first, used last), it fails for the wrong reason. **Discrimination test**: `grep -c '<pattern>' <file>` — if the count is > 1, the indexOf is ambiguous and the assertion is unreliable. **Fix**: search for a unique call-site fragment that doesn't appear in the function definition — typically the assignment LHS (`requestOrigin = parseRequestOrigin(req)`, `presented = readPresentedToken(req`). Definitions never contain the assignment target. Same trap applies to any pattern where definition and call share the same identifier syntax — method names, event listener attachments, even `console.error('[<feature>]'` template strings. Precedent: 2026-04-26 #CSRF3 implementation — section 14 source-inspection test "Origin pre-filter runs AFTER the csrfExempt short-circuit" failed at first because `indexOf('parseRequestOrigin(req)')` matched the `function parseRequestOrigin(req)` definition (line 152) before the call site (line 531); switched to `indexOf('requestOrigin = parseRequestOrigin(req)')` (assignment-form, unique to the call site). The sibling "BEFORE token verify" test passed only by coincidence — the `parseRequestOrigin` definition was already before the `readPresentedToken` definition in the file.
+
+83. **`Origin: "null"` is a real value browsers send — sandboxed iframes (`<iframe sandbox>`), `file://` pages, and some redirected requests carry the literal string `"null"` in the Origin header (and in `Sec-Fetch-Site: cross-site` flows).** Origin-checking code that does `if (origin) { /* allowlist match */ }` treats `"null"` as truthy and tries to match it. Without an explicit guard the result is wrong-for-the-right-outcome at best: the allowlist almost never contains `"null"`, so the request 403s — but for the wrong reason (it should fall through to the Referer fallback or a known-no-origin handler, not be rejected for "origin not in allowlist"). The same trap applies to CORS allowlists, CSRF Origin pre-filters, audit logging, and any code branching on `Origin`. **Fix**: add an explicit `s === 'null'` guard at the start of the Origin parser, treating `"null"` exactly like an absent header — empty result, fall through to the next signal (Referer, Sec-Fetch metadata, etc.). Document the guard with a brief comment so it isn't "cleaned up" by a future contributor who reads it as a no-op string check. Precedent: 2026-04-26 #CSRF3 implementation — `parseOriginString` at `core/plugins/lib/csrf/src/main.js:108` returns `null` (the JS literal) when input is the string `"null"`, so `parseRequestOrigin` falls back to parsing the host out of `Referer`. Two unit tests pin this behaviour: `Origin: "null"` + missing `Referer` → 403 with reason "missing origin/referer"; `Origin: "null"` + valid `Referer` → next() called. Without the guard, the missing-Referer case would have 403'd with reason "origin not allowed", masking the real problem from any operator reading the log.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gina",
-  "version": "0.3.7-alpha.9",
+  "version": "0.3.8",
   "description": "Node.js MVC framework with built-in HTTP/2, multi-bundle architecture, and scope-based data isolation — no Express dependency",
   "keywords": [
     "nodejs",
@@ -56,7 +56,7 @@
     "gina-container": "bin/gina-container",
     "gina-init": "bin/gina-init"
   },
-  "main": "./framework/v0.3.7-alpha.9/core/gna",
+  "main": "./framework/v0.3.8/core/gna",
   "types": "./types/index.d.ts",
   "typesVersions": {
     "*": {
@@ -78,7 +78,9 @@
   "license": "MIT",
   "readmeFilename": "README.md",
   "dependencies": {
-    "engine.io": "^6.0.0"
+    "@rhinostone/swig": "^1.6.0",
+    "engine.io": "^6.0.0",
+    "psl": "^1.15.0"
   },
   "devDependencies": {
     "csso-cli": "4.0.2",

package/script/post_install.js

@@ -61,14 +61,44 @@ var getUserHome = function() {
 // `colors` dependency removed in 0.3.1 — ANSI codes are now built into the logger.
 // No temporary install needed.
 
-var lib         = require('./lib');
-var console     = lib.logger;
+// Framework lib registry is intentionally not loaded here. At install time the
+// framework's nested deps (psl, @rhinostone/swig) may not yet be resolvable, and
+// `lib/domain` would crash on `require('psl')`. Node's built-in `console` is
+// sufficient for the install scripts; `console.setLevel` (a `lib.logger`-only
+// method) is gated below.
 
 var scriptPath = __dirname;
 var ginaPath = (scriptPath.replace(/\\/g, '/')).replace('/script', '');
-var help        = require(ginaPath + '/utils/helper.js');
 var pack        = ginaPath + '/package.json';
 pack =  (isWin32()) ? pack.replace(/\//g, '\\') : pack;
+
+// Pre-load framework helpers BEFORE utils/helper. utils/helper.js's init()
+// calls `require('framework/v*/lib/logger')`, which itself requires
+// `framework/v*/helpers` (lib/logger:64). When utils/helper is the outer
+// caller of lib/logger, lib/logger blocks at its helpers require and the
+// iteration's `_require` reloads path.js / task.js while lib/logger is still
+// mid-load — their module-local `var console = require('../lib/logger')`
+// then binds to a partial module.exports (= {}), so a later `console.debug`
+// in `task.js#run()` throws TypeError. Pre-loading helpers here makes
+// helpers/index.js the outer caller, so lib/logger completes inside
+// context.js's trigger and the subsequent `_require` reloads of path.js/
+// task.js see the full Logger singleton from cache.
+// Filesystem-driven version discovery so this stays correct across version
+// bumps that may temporarily skew package.json `version` and the framework
+// directory name (e.g. during a patch release window).
+try {
+    var _frameworkDir = fs.readdirSync(ginaPath + '/framework')
+        .filter(function(d) { return /^v/.test(d); })
+        .sort()
+        .pop();
+    if (_frameworkDir) {
+        require(ginaPath + '/framework/' + _frameworkDir + '/helpers');
+    }
+} catch (_e) {
+    // best-effort preload; the actual install steps will surface any real failure
+}
+
+var help        = require(ginaPath + '/utils/helper.js');
 var helpers = null;
 
 
@@ -135,7 +165,10 @@ function PostInstall() {
 
             if ( /^\-\-log-level\=/.test(args[i]) ) {
                 var logLevel = args[i].split(/\=/)[1];
-                console.setLevel(logLevel, 'gina');
+                // setLevel is a lib.logger method; Node's built-in console doesn't expose it.
+                if ( typeof(console.setLevel) === 'function' ) {
+                    console.setLevel(logLevel, 'gina');
+                }
                 process.env.LOG_LEVEL=logLevel;
             }
         }
@@ -168,7 +201,8 @@ function PostInstall() {
                     ]
                 };
                 console.warn('No `package.json` found for your project, creating one to avoid install exceptions');
-                lib.generator.createFileFromDataSync(defaultPackageJsonContent, projectPackageJsonObj.toString());
+                // Inlined to avoid loading the framework lib registry at install time.
+                fs.writeFileSync(projectPackageJsonObj.toString(), JSON.stringify(defaultPackageJsonContent, null, 4));
             }
         }
 
@@ -301,7 +335,7 @@ function PostInstall() {
                 try {
                     await promisify(funct)();
                 } catch (e) {
-                    console.error(e.toString());
+                    console.error(e && e.stack ? e.stack : e.toString());
                     process.exit(1);
                     return;
                 }