gina 0.5.26 → 0.6.0

package/framework/v0.6.0/lib/cmd/audit/verify.js

@@ -0,0 +1,294 @@
+var fs        = require('fs');
+var console   = lib.logger;
+
+var CmdHelper = require('./../helper');
+
+/**
+ * @module gina/lib/cmd/audit/verify
+ */
+/**
+ * Verifies the tamper-evidence hash chain of a bundle's audit trail
+ * (#COMPLY2 slice 3). Walks the JSONL file and recomputes every record's
+ * `hash` (`HMAC-SHA256(secret, prevHash + ':' + canonicalV1(record))`);
+ * reports the FIRST break with its line and reason, or the intact totals.
+ *
+ * Offline command — reads the trail file directly, no daemon and no running
+ * bundle needed. The chain engine is `lib.audit.verifyChain` (the single
+ * canonical implementation, shared with the tests); this handler only
+ * resolves WHICH file and WHICH key.
+ *
+ * File resolution: `--file=</abs/path>` wins; otherwise the bundle's
+ * `config/settings.json > audit.file` is replayed exactly like the boot does
+ * (absolute as-is; relative against the project root; absent → the default
+ * `<project>/logs/audit-<bundle>-<env>.jsonl`).
+ *
+ * Key resolution: `settings.json > audit.chain.secret` (a `${secret:VAR}`
+ * placeholder is resolved from `process.env[VAR]` — config-load substitution
+ * does not run offline, and `${secret:GINA_*}` names can never resolve
+ * because the CLI sweeps GINA_* out of process.env), then `GINA_AUDIT_SECRET`
+ * through the framework env reader.
+ *
+ * Exit codes: `0` chain intact (warnings, if any, are printed — read them) ·
+ * `1` chain BROKEN · `2` usage/config error (no trail file, no key, bad --env).
+ *
+ * Usage:
+ *  gina audit:verify <bundle> @<project>
+ *  gina audit:verify <bundle> @<project> --env=prod
+ *  gina audit:verify <bundle> @<project> --file=/var/log/audit-web-prod.jsonl
+ *  gina audit:verify <bundle> @<project> --format=json
+ *
+ * @class Verify
+ * @constructor
+ * @param {object} opt - Parsed command-line options
+ * @param {object} opt.client - Socket client for terminal output
+ * @param {string[]} opt.argv - Full argv array
+ * @param {number} [opt.debugPort] - Node.js inspector port
+ * @param {boolean} [opt.debugBrkEnabled] - True when --inspect-brk is active
+ * @param {object} cmd - The cmd dispatcher object (lib/cmd/index.js)
+ *
+ * @example
+ *  $ gina audit:verify web @myproject --env=prod
+ *  [ audit:verify ] /srv/myproject/logs/audit-web-prod.jsonl
+ *  OK — chain intact: 1042 chained record(s), 17 pre-chain record(s)
+ */
+function Verify(opt, cmd) {
+    var self  = {};
+    var local = { bundle: null, env: null, file: null, secret: null };
+
+    /**
+     * Wires CmdHelper, parses the bundle positional, resolves env / trail
+     * file / signing key, then runs the verification.
+     *
+     * @inner
+     * @private
+     */
+    var init = function() {
+
+        new CmdHelper(self, opt.client, { port: opt.debugPort, brkEnabled: opt.debugBrkEnabled });
+        if (!isCmdConfigured()) return false;
+
+        // ONE positional (the bundle). CmdHelper's positional cleanup only
+        // runs for `bundle:` tasks, so parse argv directly: everything after
+        // the task token that is neither `@<project>` nor a `--flag`.
+        var positionals = [];
+        for (var i = 3; i < opt.argv.length; ++i) {
+            if ( /^\@/.test(opt.argv[i]) || /^--/.test(opt.argv[i]) ) continue;
+            positionals.push(opt.argv[i]);
+        }
+        if ( positionals.length !== 1 ) {
+            console.error('audit:verify requires a bundle: gina audit:verify <bundle> @<project> [--env=<env>] [--file=</abs/path>] [--format=json]');
+            process.exit(2);
+            return;
+        }
+        local.bundle = positionals[0];
+
+        if ( self.projectName == null || typeof(self.projects[self.projectName]) == 'undefined' ) {
+            console.error('[ '+ self.projectName +' ] is not a registered project.');
+            process.exit(2);
+            return;
+        }
+
+        if ( !resolveEnv() || !resolveFile() || !resolveSecret() ) {
+            return; // each resolver exits with code 2 on failure
+        }
+
+        run();
+    };
+
+    /**
+     * Resolves the env: `--env` when given (validated against the project's
+     * env list — the CmdHelper `--env` override only fires for lifecycle
+     * tasks, so read `self.params` directly), else the project default.
+     *
+     * @inner
+     * @private
+     * @returns {boolean}
+     */
+    var resolveEnv = function() {
+        var p = self.params || {};
+        if ( typeof(p.env) != 'undefined' ) {
+            if ( !Array.isArray(self.envs) || self.envs.indexOf(p.env) < 0 ) {
+                console.error('Environment `'+ p.env +'` not found in your project [ '+ self.projectName +' ]');
+                process.exit(2);
+                return false;
+            }
+            local.env = p.env;
+        } else {
+            local.env = self.projects[self.projectName].def_env;
+        }
+        return true;
+    };
+
+    /**
+     * Resolves the trail file: `--file` (absolute) wins; otherwise replays the
+     * boot's derivation from the bundle's `config/settings.json > audit`.
+     *
+     * @inner
+     * @private
+     * @returns {boolean}
+     */
+    var resolveFile = function() {
+        var p = self.params || {};
+        if ( typeof(p.file) != 'undefined' ) {
+            if ( typeof(p.file) != 'string' || !/^\//.test(p.file) ) {
+                console.error('--file must be an absolute path.');
+                process.exit(2);
+                return false;
+            }
+            local.file = p.file;
+            return true;
+        }
+
+        var projectPath = self.projects[self.projectName].path;
+        var srcEntry = ( self.bundlesByProject && self.bundlesByProject[self.projectName] )
+            ? self.bundlesByProject[self.projectName][local.bundle]
+            : null;
+        if ( !srcEntry ) {
+            console.error('Bundle [ '+ local.bundle +' ] is not registered inside `@'+ self.projectName +'`.');
+            process.exit(2);
+            return false;
+        }
+
+        var auditSettings = readAuditSettings(projectPath, srcEntry.src);
+        if ( auditSettings && auditSettings.store ) {
+            console.error('Bundle [ '+ local.bundle +' ] uses the connector store backend (`audit.store`) — the chain requires the file backend, so there is no trail file to derive. Pass --file explicitly if a file trail exists elsewhere.');
+            process.exit(2);
+            return false;
+        }
+
+        var file = ( auditSettings && typeof(auditSettings.file) == 'string' && auditSettings.file ) ? auditSettings.file : null;
+        if ( !file || !/^\//.test(file) ) {
+            file = file
+                ? projectPath + '/' + file
+                : projectPath + '/logs/audit-'+ local.bundle +'-'+ local.env +'.jsonl';
+        }
+        local.file = _(file, true).toString();
+        return true;
+    };
+
+    /**
+     * Reads the bundle's `settings.json > audit` block — `requireJSON`, never
+     * `JSON.parse` (settings files routinely carry `//` comments). A missing
+     * or unreadable file falls through to `null` (the defaults still let the
+     * default trail path be derived).
+     *
+     * @inner
+     * @private
+     * @param {string} projectPath
+     * @param {string} srcRel - the bundle's `src` entry from manifest.json
+     * @returns {?object}
+     */
+    var readAuditSettings = function(projectPath, srcRel) {
+        try {
+            var settingsPath = _(projectPath + '/' + srcRel + '/config/settings.json', true);
+            if ( !fs.existsSync(settingsPath.toString()) ) return null;
+            var settings = requireJSON(settingsPath);
+            return ( settings && typeof(settings.audit) == 'object' && settings.audit ) ? settings.audit : null;
+        } catch (err) {
+            return null;
+        }
+    };
+
+    /**
+     * Resolves the signing key: `audit.chain.secret` (literal, or a
+     * `${secret:VAR}` placeholder resolved from `process.env[VAR]`), then
+     * `GINA_AUDIT_SECRET` through the framework env reader (direct
+     * `process.env` fallback for non-CLI contexts).
+     *
+     * @inner
+     * @private
+     * @returns {boolean}
+     */
+    var resolveSecret = function() {
+        var projectPath = self.projects[self.projectName].path;
+        var srcEntry = ( self.bundlesByProject && self.bundlesByProject[self.projectName] )
+            ? self.bundlesByProject[self.projectName][local.bundle]
+            : null;
+        var auditSettings = srcEntry ? readAuditSettings(projectPath, srcEntry.src) : null;
+
+        var secret = ( auditSettings && auditSettings.chain && typeof(auditSettings.chain.secret) == 'string' && auditSettings.chain.secret )
+            ? auditSettings.chain.secret
+            : null;
+        if ( secret ) {
+            var m = secret.match(/^\$\{secret:([^}]+)\}$/);
+            if ( m ) {
+                secret = process.env[m[1]] || null;
+                if ( !secret ) {
+                    console.error('`audit.chain.secret` names `${secret:'+ m[1] +'}` but `'+ m[1] +'` is not set in this shell. Export it, or set GINA_AUDIT_SECRET. (Note: `${secret:GINA_*}` names can never resolve — the CLI sweeps GINA_* out of process.env.)');
+                    process.exit(2);
+                    return false;
+                }
+            }
+        }
+        if ( !secret ) {
+            secret = ( typeof(getEnvVar) == 'function' && getEnvVar('GINA_AUDIT_SECRET') ) || process.env.GINA_AUDIT_SECRET || null;
+        }
+        if ( !secret ) {
+            console.error('No signing key found — set `settings.json > audit.chain.secret` for [ '+ local.bundle +' ], or export GINA_AUDIT_SECRET.');
+            process.exit(2);
+            return false;
+        }
+        local.secret = secret;
+        return true;
+    };
+
+    /**
+     * Runs `lib.audit.verifyChain` and emits the report. Output goes through
+     * `fs.writeSync(1, ...)` — `process.exit` right after an async stdout
+     * write truncates on a pipe (the connector:infer lesson), and a verify
+     * verdict must never be lost mid-pipe.
+     *
+     * @inner
+     * @private
+     */
+    var run = function() {
+        if ( !fs.existsSync(local.file) ) {
+            console.error('No trail found at '+ local.file +' — nothing to verify. (A missing trail is NOT a pass.)');
+            process.exit(2);
+            return;
+        }
+
+        var result = lib.audit.verifyChain(local.file, local.secret);
+        var jsonMode = ( self.params && self.params.format === 'json' );
+        var out = '';
+
+        if ( jsonMode ) {
+            result.file = local.file;
+            out = JSON.stringify(result) + '\n';
+        } else {
+            out = '[ audit:verify ] '+ local.file +'\n';
+            if ( result.ok ) {
+                out += ( result.records === 0 && result.unchained === 0 )
+                    ? 'OK — empty trail (0 records)\n'
+                    : 'OK — chain intact: '+ result.records +' chained record(s), '+ result.unchained +' pre-chain record(s)\n';
+            } else {
+                out += 'FAIL — break at line '+ result.breakAt.line +': '+ result.breakAt.reason +'\n';
+                out += '  '+ result.records +' record(s) verified before the break. Remediation: investigate, then rotate the file aside to re-baseline the chain.\n';
+            }
+            for (var w = 0; w < result.warnings.length; ++w) {
+                out += '  warning — line '+ result.warnings[w].line +': '+ result.warnings[w].type +'\n';
+            }
+        }
+
+        fs.writeSync(1, out);
+        end(result.ok ? 0 : 1);
+    };
+
+    /**
+     * Terminates the command: closes the client socket when live, then exits.
+     *
+     * @inner
+     * @private
+     * @param {number} code
+     */
+    var end = function(code) {
+        if ( opt.client && typeof(opt.client.emit) == 'function' ) {
+            try { opt.client.emit('end'); } catch (err) { /* offline mode has no live socket */ }
+        }
+        process.exit(code);
+    };
+
+    init();
+}
+
+module.exports = Verify;

package/framework/{v0.5.26 → v0.6.0}/lib/cmd/framework/init.js

@@ -733,6 +733,17 @@ function Initialize(opt) {
                 setEnvVar('GINA_HOST_V4', localUserSettings.host_v4);
             }
         }
+        // #B161 — bind_host was the only connection key WITHOUT a disk -> env
+        // read-back here, so the regeneration below (dic + createFileFromDataSync)
+        // reverted a value written by `gina framework:set --bind-host=` to the
+        // default on the very next CLI invocation. Mirror the host_v4 block
+        // above so the persisted value survives. The `${` guard skips the
+        // unresolved template placeholder a fresh/broken install may carry.
+        if ( !getEnvVar('GINA_BIND_HOST') && targetObj.existsSync() ) {
+            if ( typeof(localUserSettings.bind_host) != 'undefined' && String(localUserSettings.bind_host).indexOf('${') < 0 ) {
+                setEnvVar('GINA_BIND_HOST', localUserSettings.bind_host);
+            }
+        }
         if ( !getEnvVar('GINA_HOSTNAME') && targetObj.existsSync() ) {
             if ( typeof(localUserSettings.hostname) != 'undefined' ) {
                 setEnvVar('GINA_HOSTNAME', localUserSettings.hostname);

package/framework/{v0.5.26 → v0.6.0}/lib/cmd/framework/tail.js

@@ -9,6 +9,8 @@ var EventEmitter    = require('events').EventEmitter;
 var e               = new EventEmitter();
 
 var CmdHelper       = require('./../helper');
+// #B160 — control-plane dial-host resolution (pure, no framework globals)
+var netLocality     = require(__dirname + '/../../net-locality');
 var console         = lib.logger;
 var LoggerHelper    = require( _(GINA_FRAMEWORK_DIR + '/lib/logger/src/helper.js', true) );
 /**
@@ -99,7 +101,9 @@ function Tail(opt, cmd) {
     var tail = function(opt, cmd, isResuming) {
 
         var port = opt.mqPort || GINA_MQ_PORT || 8125;
-        var host = opt.hostV4 || GINA_HOST_V4 || '127.0.0.1';
+        // #B160 — the MQ listener binds `bind_host` (loopback by default):
+        // dial it when host_v4 is one of this machine's own addresses.
+        var host = netLocality.resolveDialHost(opt.hostV4 || GINA_HOST_V4 || '127.0.0.1', getEnvVar('GINA_BIND_HOST'));
         var clientOptions = {
             host    : host,
             port    : port,

package/framework/{v0.5.26 → v0.6.0}/lib/cmd/gina.1.md

@@ -29,6 +29,7 @@ model
 dev
 view
 service
+audit
 
 ## ENVIRONMENT
 

package/framework/{v0.5.26 → v0.6.0}/lib/index.js

@@ -173,6 +173,13 @@ function Lib() {
         // per-request require() can never grow a dead-`children` tail (#B32-residual).
         // It also keeps a security gate out of the dev-mode hot-reload path entirely.
         authzGate       : require('./authz-gate'),
+        // #COMPLY3 — authentication hardening primitives (password hashing +
+        // verification, password policy, lockout, TOTP). require() — NOT _require —
+        // for the authzGate reason above: a security primitive stays out of the
+        // dev-mode hot-reload path entirely. It also holds module-scope state the
+        // hot-reload would discard on every dev request: the scrypt concurrency
+        // gauge and its FIFO queue (a discarded queue strands in-flight logins).
+        authn           : require('./authn'),
         // #COMPLY2 — the audit-trail primitive behind self.audit() and the authz
         // auto-events. Holds the boot-adopted store (an open O_APPEND fd for the
         // default file backend), the serialized write queue and the written/dropped
@@ -198,6 +205,12 @@ function Lib() {
         // readPidfile) for the bundle:list / service:list / bundle:status /
         // project:status CLI handlers. Pure (same contract as routing-introspect).
         cmdStatusFormat : _require('./cmd-status-format'),
+        // #B160 — control-plane dial-host resolution: is host_v4 one of this
+        // machine's own interfaces, and which address should a CLI-side client
+        // dial (`bind_host` vs `host_v4`)? Pure + stateless (only reads
+        // os.networkInterfaces()), so the dev-mode-hot-reloadable _require is
+        // safe — same contract as routing-introspect above.
+        netLocality     : _require('./net-locality'),
         // Single source of truth for the connector driver → npm package + semver
         // range mapping. Consumed by the connector:* CLI handlers (connector:add
         // install hint + connector:add --install range resolution + connector:list

package/framework/{v0.5.26 → v0.6.0}/lib/logger/src/containers/file/index.js

@@ -12,6 +12,8 @@ var helpers = null;
 
 // #M22 — merge-eval fallback removed (sister fix to lib/merge/src/main.js direct json_clone require)
 var merge     = require(__dirname + '/../../../../merge');
+// #B160 — control-plane dial-host resolution (pure, no framework globals)
+var netLocality = require(__dirname + '/../../../../net-locality');
 
 function FileContainer(opt, loggers) {
     var self = {
@@ -55,6 +57,9 @@ function FileContainer(opt, loggers) {
 
         opt.mqPort = settings.mq_port;
         opt.hostV4 = settings.host_v4;
+        // #B160 — carry the daemon's bind address for the dial-host
+        // resolution in onPayload().
+        opt.bindHost = settings.bind_host;
         // ---------- EO - hack for early calls
 
         // handle server not started yet or server exited
@@ -153,7 +158,12 @@ function FileContainer(opt, loggers) {
     function onPayload(opt, isResuming) {
         // console.debug('mqFile options: ', JSON.stringify(opt, null, 2));
         var port = opt.mqPort || getEnvVar('GINA_MQ_PORT') || 8125;// jshint ignore:line
-        var host = opt.hostV4 || getEnvVar('GINA_HOST_V4') || '127.0.0.1';// jshint ignore:line
+        // #B160 — the MQ listener binds `bind_host` (loopback by default):
+        // dial it when host_v4 is one of this machine's own addresses.
+        var host = netLocality.resolveDialHost(
+            opt.hostV4 || getEnvVar('GINA_HOST_V4') || '127.0.0.1',
+            opt.bindHost || getEnvVar('GINA_BIND_HOST')
+        );// jshint ignore:line
         var clientOptions = {
             host    : host,
             port    : port,

package/framework/{v0.5.26 → v0.6.0}/lib/logger/src/containers/mq/speaker.js

@@ -1,6 +1,8 @@
 'use strict';
 // Imports
 const net = require('net');
+// #B160 — control-plane dial-host resolution (pure, no framework globals)
+var netLocality = require(__dirname + '/../../../../net-locality');
 // var fs                  = require('fs');
 // var util                = require('util');
 
@@ -42,6 +44,9 @@ function MQSpeaker(opt, loggers, cb) {
         var _mqPort = ~~settings.mq_port;
         opt.mqPort = (_mqPort > 0 && _mqPort < 65536) ? _mqPort : 8125;
         opt.hostV4 = settings.host_v4;
+        // #B160 — carry the daemon's bind address so startMQSpeaker() can
+        // dial locally when host_v4 names one of this machine's interfaces.
+        opt.bindHost = settings.bind_host;
         // ---------- EO - hack for early calls
 
         return startMQSpeaker(opt, cb);
@@ -50,7 +55,9 @@ function MQSpeaker(opt, loggers, cb) {
 
     function startMQSpeaker(opt, cb) {
         var port = opt.mqPort || 8125;// jshint ignore:line
-        var host = opt.hostV4 || '127.0.0.1';// jshint ignore:line
+        // #B160 — the MQ listener binds `bind_host` (loopback by default):
+        // dial it when host_v4 is one of this machine's own addresses.
+        var host = netLocality.resolveDialHost(opt.hostV4 || '127.0.0.1', opt.bindHost);// jshint ignore:line
         var clientOptions = {
             host    : host,
             port    : port,

package/framework/v0.6.0/lib/net-locality/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "gina-lib-net-locality",
+  "version": "1.0.0",
+  "description": "Control-plane dial-host resolution: decides whether `host_v4` names one of this machine's own interfaces and which address a CLI-side client should dial (`bind_host` vs `host_v4`).",
+  "authors": [
+    {
+      "name": "Martin-Luther ETOUMAN",
+      "email": "contact@gina.io"
+    }
+  ],
+  "copyright": "Copyright (c) 2009-2026 Rhinostone <contact@gina.io>",
+  "engines": {
+    "node": ">=0.10.22"
+  },
+  "main": "src/main",
+  "license": "MIT"
+}

package/framework/v0.6.0/lib/net-locality/src/main.js

@@ -0,0 +1,174 @@
+/**
+ * Gina — net-locality helpers (control-plane dial-host resolution).
+ *
+ * The framework daemon binds its control sockets — the command socket (8124)
+ * and the MQ listener (8125) — to `bind_host`, loopback by default, while
+ * `host_v4` is the address EXTERNAL clients use to reach this machine. The
+ * CLI-side clients (command socket dial, MQ speaker, MQ file container,
+ * `gina tail`) historically dialled `host_v4` — so whenever `host_v4` was set
+ * to a non-loopback address of this very machine (the common containerized
+ * shape, where it carries the container/LAN IP so siblings can reach the
+ * bundles), the co-located client dialled an address the daemon does not
+ * bind, and the control plane was unreachable from its own host.
+ *
+ * The resolution deliberately stays on the DIAL side: when `host_v4` names
+ * one of this machine's own interfaces, the daemon being dialled is local,
+ * so the client dials the address the daemon actually binds. The BIND side
+ * stays untouched — widening it remains a deliberate opt-in.
+ *
+ * Pure module: no framework globals, no state. `os.networkInterfaces()` is
+ * the only system dependency and is injectable for deterministic tests.
+ *
+ * @module gina/lib/net-locality
+ */
+'use strict';
+
+var os = require('os');
+
+/**
+ * Normalizes an address for comparison: trims, lowercases, strips an
+ * IPv4-mapped IPv6 prefix (`::ffff:1.2.3.4` → `1.2.3.4`) and an IPv6 zone
+ * suffix (`fe80::1%en0` → `fe80::1`).
+ *
+ * @inner
+ * @private
+ * @param {string} host - Raw host string
+ * @returns {string} Normalized host
+ */
+var normalizeHost = function(host) {
+    var h = String(host).trim().toLowerCase();
+    if (h.indexOf('::ffff:') === 0 && h.indexOf('.') > -1) {
+        h = h.substring(7);
+    }
+    var zone = h.indexOf('%');
+    if (zone > -1) {
+        h = h.substring(0, zone);
+    }
+    return h;
+};
+
+/**
+ * True when the (normalized) host is a loopback name or address:
+ * `localhost`, anything in `127.0.0.0/8`, or `::1`.
+ *
+ * @inner
+ * @private
+ * @param {string} h - Normalized host (see `normalizeHost`)
+ * @returns {boolean}
+ */
+var isLoopback = function(h) {
+    return ( h === 'localhost' || h === '::1' || /^127\./.test(h) );
+};
+
+/**
+ * True when the (normalized) host is a wildcard bind address (`0.0.0.0` or
+ * `::`) — an address that can be listened on but never meaningfully dialled.
+ *
+ * @inner
+ * @private
+ * @param {string} h - Normalized host (see `normalizeHost`)
+ * @returns {boolean}
+ */
+var isWildcard = function(h) {
+    return ( h === '0.0.0.0' || h === '::' );
+};
+
+/**
+ * Tells whether `host` is an address assigned to one of this machine's own
+ * network interfaces (exact match after normalization). Loopback always
+ * qualifies. A hostname never matches — only literal addresses are compared,
+ * so `my-host.local` falls through to `false` by design. Any enumeration
+ * failure also returns `false` (fail-safe: callers keep today's unmodified
+ * dial behaviour).
+ *
+ * @param {string} host - Literal IP address to test
+ * @param {object} [interfaces] - `os.networkInterfaces()`-shaped map; used by
+ *  tests for determinism. Defaults to the live `os.networkInterfaces()`.
+ * @returns {boolean} True when the address belongs to this machine
+ *
+ * @example
+ *  isLocalAddress('127.0.0.1');      // true
+ *  isLocalAddress('192.0.2.1');      // false (TEST-NET, not a local iface)
+ *  isLocalAddress('my-host.local');  // false (hostname, not an address)
+ */
+var isLocalAddress = function(host, interfaces) {
+    if ( typeof(host) !== 'string' || host === '' ) {
+        return false;
+    }
+    var h = normalizeHost(host);
+    if ( isLoopback(h) ) {
+        return true;
+    }
+    try {
+        var ifaces = interfaces || os.networkInterfaces();
+        for (var name in ifaces) {
+            var addrs = ifaces[name];
+            if ( !Array.isArray(addrs) ) {
+                continue;
+            }
+            for (var i = 0, len = addrs.length; i < len; i++) {
+                var a = addrs[i] && addrs[i].address;
+                if ( typeof(a) === 'string' && normalizeHost(a) === h ) {
+                    return true;
+                }
+            }
+        }
+    } catch (err) {
+        return false;
+    }
+    return false;
+};
+
+/**
+ * Resolves the host a control-plane CLIENT should dial.
+ *
+ * Rules, in order:
+ *  1. No usable `hostV4` → `127.0.0.1` (the historical fallback).
+ *  2. `hostV4` is loopback → returned unchanged (already dial-safe).
+ *  3. `hostV4` does NOT name one of this machine's interfaces (a hostname, a
+ *     genuinely remote address, or interface enumeration failed) → returned
+ *     unchanged: remote administration keeps working exactly as before.
+ *  4. `hostV4` names a local interface → the daemon is local, so dial what it
+ *     binds: `bindHost` when it is a concrete non-wildcard address,
+ *     `127.0.0.1` otherwise (a wildcard bind includes loopback).
+ *
+ * @param {string} hostV4 - The resolved client-facing host (`host_v4`)
+ * @param {string} [bindHost] - The daemon's `bind_host`, when known
+ * @param {object} [interfaces] - `os.networkInterfaces()`-shaped map; used by
+ *  tests for determinism. Defaults to the live `os.networkInterfaces()`.
+ * @returns {string} The host to dial
+ *
+ * @example
+ *  // co-located daemon, LAN-facing host_v4 (the containerized shape)
+ *  resolveDialHost('192.168.1.20', '127.0.0.1'); // '127.0.0.1' (when local)
+ *  // operator widened the bind to a concrete address
+ *  resolveDialHost('192.168.1.20', '192.168.1.20'); // '192.168.1.20'
+ *  // wildcard bind still dials loopback
+ *  resolveDialHost('192.168.1.20', '0.0.0.0');   // '127.0.0.1' (when local)
+ *  // remote daemon: unchanged
+ *  resolveDialHost('203.0.113.7', '127.0.0.1');  // '203.0.113.7'
+ */
+var resolveDialHost = function(hostV4, bindHost, interfaces) {
+    if ( typeof(hostV4) !== 'string' || hostV4 === '' ) {
+        return '127.0.0.1';
+    }
+    var h = normalizeHost(hostV4);
+    if ( isLoopback(h) ) {
+        return hostV4;
+    }
+    if ( !isLocalAddress(h, interfaces) ) {
+        return hostV4;
+    }
+    if ( typeof(bindHost) === 'string' && bindHost !== '' ) {
+        var b = normalizeHost(bindHost);
+        if ( !isWildcard(b) ) {
+            return bindHost;
+        }
+    }
+    return '127.0.0.1';
+};
+
+module.exports = {
+    isLocalAddress  : isLocalAddress,
+    resolveDialHost : resolveDialHost
+};

package/framework/{v0.5.26 → v0.6.0}/lib/nunjucks-filters/src/main.js

@@ -356,8 +356,21 @@ function NunjucksFilters(conf) {
             // latch/global, byte-identical.
             url.isProxyHost = isProxyHost;
             if (isProxyHost) {
+                // #B168 — hold getRoute's own resolution: with no per-request slot and
+                // no worker global, the override below must not replace a usable
+                // envConf-derived value with an unset one
+                var _routeProxyHostname = url.proxy_hostname;
                 url.proxy_hostname    = (isGFFCtx) ? window.location.protocol +'//'+ document.location.hostname : ( (ctx.req && ctx.req._ginaProxyHostname) || process.gina.PROXY_HOSTNAME );
                 url.proxy_host        = url.hostname.replace(/(https|http)\:\/\//, '');
+                if ( !url.proxy_hostname ) {
+                    url.proxy_hostname = _routeProxyHostname;
+                    if ( !url.proxy_hostname ) {
+                        // #B168 — nothing resolvable anywhere: degrade to the route's
+                        // direct hostname; toUrl() keys on isProxyHost, so leaving it
+                        // true would stringify the unset value into the emitted URL
+                        url.isProxyHost = false;
+                    }
+                }
             }
             url = url.toUrl();