gina 0.5.25 → 0.5.26

package/framework/{v0.5.25 → v0.5.26}/lib/cmd/bundle/mcp-start.js

@@ -237,6 +237,7 @@ function MCPStart(opt, cmd) {
         var port           = resolveHttpPort(mcpDoc);
         var authToken      = resolveAuthToken(mcpDoc);
         var allowedOrigins = resolveAllowedOrigins(mcpDoc);
+        var allowInsecure  = resolveAllowInsecure(mcpDoc);
 
         httpTransport = mcpHttp.createHttpTransport({
             mcpServer:      server,
@@ -244,13 +245,16 @@ function MCPStart(opt, cmd) {
             port:           port,
             authToken:      authToken,
             allowedOrigins: allowedOrigins,
+            allowInsecure:  allowInsecure,
             onError: function(err) {
                 console.error('[ '+ bundle +' ][mcp] HTTP transport: ' + (err && err.message || err));
             }
         });
 
         httpTransport.start().then(function(info) {
-            var authNote = authToken ? ' (bearer auth: enabled)' : '';
+            var authNote = authToken
+                ? ' (bearer auth: enabled)'
+                : (allowInsecure ? ' (bearer auth: none — allowInsecure asserted)' : '');
             console.info('[ '+ bundle +' ][mcp] MCP server listening on http://'+ info.host +':'+ info.port + authNote +'. Dispatch target: '+ baseUrl +' (timeout: '+ timeoutMs +' ms, maxInFlight: '+ maxInFlight +'). '+ mcpDoc.tools.length +' tool'+ (mcpDoc.tools.length === 1 ? '' : 's') +' exposed.');
         }, function(err) {
             return end( new Error('Failed to start HTTP transport on '+ host +':'+ port +': '+ (err && err.message || err)) );
@@ -360,9 +364,15 @@ function MCPStart(opt, cmd) {
      * Resolves the HTTP bind host. Precedence:
      *   1. `--http-host=<host>` CLI flag
      *   2. `mcp.json > server > httpHost`
-     *   3. `process.env.GINA_HOST_V4` (set by bin/cli from
-     *      `~/.gina/<shortVersion>/settings.json > host_v4`)
-     *   4. `'127.0.0.1'` ultimate fallback
+     *   3. `process.env.GINA_HOST_V4` — INERT under the CLI. `filterArgs()`
+     *      moves every GINA_* key into `process.gina` and deletes it from
+     *      `process.env`, so this read is always undefined there.
+     *      Deliberately NOT converted to `getEnvVar` the way the auth-token
+     *      tier was: `host_v4` is the address clients CONNECT to (commonly a
+     *      LAN address), never a bind address — reviving this tier would move
+     *      the default bind OFF loopback and expose the transport. The correct
+     *      replacement is `bind_host` / `GINA_BIND_HOST`, tracked separately.
+     *   4. `'127.0.0.1'` — in practice the effective default, per (3).
      *
      * @private
      * @param   {object} mcpDoc
@@ -429,12 +439,44 @@ function MCPStart(opt, cmd) {
         if (mcpDoc && mcpDoc.server && typeof(mcpDoc.server.authToken) === 'string' && mcpDoc.server.authToken) {
             return mcpDoc.server.authToken;
         }
-        var env = process.env.GINA_MCP_AUTH_TOKEN;
+        // `filterArgs()` (bin/cli) moves every GINA_* key OUT of `process.env`
+        // into `process.gina` and deletes the original, so a bare
+        // `process.env.GINA_MCP_AUTH_TOKEN` read is always undefined under the
+        // CLI — the documented env path silently yielded NO token, leaving the
+        // transport unauthenticated. `getEnvVar` is the supported reader; the
+        // direct read stays as the fallback for embedders that never ran the sweep.
+        var env = (typeof(getEnvVar) === 'function' && getEnvVar('GINA_MCP_AUTH_TOKEN'))
+                  || process.env.GINA_MCP_AUTH_TOKEN;
         if (typeof(env) === 'string' && env) return env;
         return null;
     };
 
 
+    /**
+     * Resolves the insecure-transport waiver. Precedence:
+     *   1. `--allow-insecure` CLI flag
+     *   2. `mcp.json > server > allowInsecure` (strict boolean)
+     *   3. `false`
+     *
+     * Only meaningful when no bearer token is configured: it tells the
+     * transport that a non-loopback bind (or a wildcard Origin allowlist) is
+     * fronted by something else — a mesh, a NetworkPolicy, or an
+     * authenticating reverse proxy — rather than genuinely open.
+     *
+     * @private
+     * @param   {object} mcpDoc
+     * @returns {boolean}
+     */
+    var resolveAllowInsecure = function(mcpDoc) {
+        var cli = self.params && self.params['allow-insecure'];
+        if (cli === true || cli === 'true') return true;
+        if (mcpDoc && mcpDoc.server && mcpDoc.server.allowInsecure === true) {
+            return true;
+        }
+        return false;
+    };
+
+
     /**
      * Resolves the CORS `Origin` allowlist. Precedence:
      *   1. `--cors-origin=<list>` CLI flag (comma-separated; use `*` to disable)

package/framework/{v0.5.25 → v0.5.26}/lib/cmd/bundle/openapi.js

@@ -198,11 +198,37 @@ function OpenAPI(opt, cmd) {
     };
 
 
+    /**
+     * #COMPLY10 — reads `auth.requireAuthByDefault`, the deny-by-default mode.
+     *
+     * The published spec has to agree with the runtime, and under this mode an
+     * UN-annotated route is gated. Without reading it here the spec would declare
+     * those routes unauthenticated while every call to them answers 401 — a
+     * published contract that lies about its own security, which is worse than
+     * publishing none.
+     *
+     * Strict `=== true`, matching the boot lint: a truthy string does not enable
+     * the mode at runtime, so it must not enable it in the spec either.
+     *
+     * @private
+     * @param {object|null} settings - Parsed settings.json (may be null)
+     * @returns {boolean} True when un-annotated routes are gated by default
+     */
+    var hasRequireAuthByDefault = function(settings) {
+        if ( !settings || typeof(settings.auth) != 'object' || settings.auth === null ) {
+            return false;
+        }
+        return ( settings.auth.requireAuthByDefault === true );
+    };
+
+
     /**
      * Applies the authorization contract to an operation when its route is
      * gated. A route is gated exactly when the runtime authz gate would act:
      * `param.requireAuth === true`, a non-empty `param.roles` array, or a
-     * non-empty `param.policy` string (roles/policy imply requireAuth).
+     * non-empty `param.policy` string (roles/policy imply requireAuth) — or,
+     * under #COMPLY10 deny-by-default, when the route declares none of those and
+     * is not marked `param.public: true`.
      *
      * Emits the observable contract only: a `401` response on every gated
      * route (+ a `403` when roles/policy add authorization beyond
@@ -216,12 +242,18 @@ function OpenAPI(opt, cmd) {
      * @param {object} operation - The OpenAPI operation object (mutated in place)
      * @param {object} param - The route's `param` block (`route.param || {}`)
      * @param {boolean} machineAuth - True when the `bearerAuth` scheme is emitted
+     * @param {boolean} defaultDeny - True when `auth.requireAuthByDefault` is on (#COMPLY10)
      * @returns {undefined}
      */
-    var applyAuthContract = function(operation, param, machineAuth) {
+    var applyAuthContract = function(operation, param, machineAuth, defaultDeny) {
         var hasRoles    = ( Array.isArray(param.roles) && param.roles.length > 0 );
         var hasPolicy   = ( typeof(param.policy) == 'string' && param.policy !== '' );
-        var isGated     = ( param.requireAuth === true || hasRoles || hasPolicy );
+        // #COMPLY10 — under deny-by-default an un-annotated route is gated unless it
+        // is explicitly `public`, so the spec must treat it as gated too. Mirrors the
+        // gate's own precedence (lib/authz-gate): `public` only ever exempts a route
+        // that declares no explicit key, so it can never un-gate an annotated one.
+        var byDefault   = ( defaultDeny === true && param.public !== true );
+        var isGated     = ( param.requireAuth === true || hasRoles || hasPolicy || byDefault );
 
         if ( !isGated ) return;
 
@@ -285,6 +317,7 @@ function OpenAPI(opt, cmd) {
         // bundle's spec gains no components block. The scheme matches the wire's
         // own advertisement — the machine 401 challenges with
         // `WWW-Authenticate: Bearer`.
+        var defaultDeny = hasRequireAuthByDefault(settings);
         var machineAuth = hasMachineAuth(settings);
         if (machineAuth) {
             spec.components = {
@@ -332,7 +365,7 @@ function OpenAPI(opt, cmd) {
                     var operation = buildOperation(routeName, route, urlInfo.params, namespace, methods.length > 1, method, srcPath);
 
                     // Authorization contract for gated routes
-                    applyAuthContract(operation, route.param || {}, machineAuth);
+                    applyAuthContract(operation, route.param || {}, machineAuth, defaultDeny);
 
                     spec.paths[oaPath][method] = operation;
                 }

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

@@ -153,8 +153,24 @@ function Initialize(opt) {
      */
     var run = function(opt, cmd) {
         opt.task = checkForAliases(opt.task);
+
+        // The resolved topic/action pair becomes the `require()` path below, and
+        // for an online command it is supplied by the caller over the framework
+        // socket. Constrain both segments to the shipped command namespace so a
+        // name can only ever resolve INSIDE `lib/cmd/`. Every command group
+        // directory and action file gina ships matches this pattern, including
+        // the synthetic `framework:-V` / `framework:--version` forms; anything
+        // carrying a path separator or a `..` segment does not.
+        var isSafeCmdSegment = function (segment) {
+            return /^[A-Za-z0-9_-]+$/.test( String(segment) );
+        };
+        var isKnownNamespace = isSafeCmdSegment(opt.task.topic) && isSafeCmdSegment(opt.task.action);
+
         var filename ='/cmd/' + opt.task.topic + '/' + opt.task.action + '.js'
-        var path = getPath('gina').lib + filename;
+        // A segment outside that namespace resolves to '' — which never exists —
+        // so it falls into the same "not a valid command" branch as an unknown
+        // action below, and can never reach require().
+        var path = isKnownNamespace ? getPath('gina').lib + filename : '';
 
         // Unknown command → print a clean, actionable message instead of a raw
         // `Cannot find module` stack. `bin/cli` already rejects an unknown GROUP
@@ -183,6 +199,13 @@ function Initialize(opt) {
             if (opt.client) {
                 opt.client.write(message + '\n');
             }
+
+            // Online runs inside the long-lived daemon serving every client, so
+            // exiting here would drop the control plane. End this client instead.
+            if ( opt.isOnlineCommand ) {
+                if (opt.client) { opt.client.end(); }
+                return;
+            }
             process.exit(1);
             return;
         }
@@ -666,6 +689,7 @@ function Initialize(opt) {
                         'debug_port' : 'GINA_DEBUG_PORT',
                         'mq_port'    : 'GINA_MQ_PORT',
                         'host_v4'    : 'GINA_HOST_V4',
+                        'bind_host'  : 'GINA_BIND_HOST',
                         'hostname'   : 'GINA_HOSTNAME',
                         'logdir'     : 'GINA_LOGDIR',
                         'tmpdir'     : 'GINA_TMPDIR',
@@ -764,6 +788,9 @@ function Initialize(opt) {
                 'port' : getEnvVar('GINA_PORT') || 8124, // TODO - scan for the next available port
                 'debug_port' : getEnvVar('GINA_DEBUG_PORT') || process.debugPort || 9339,
                 'host_v4' : getEnvVar('GINA_HOST_V4') || '127.0.0.1',
+                // Bind address for the framework control sockets — loopback by
+                // default; widen deliberately to expose them beyond this host.
+                'bind_host' : getEnvVar('GINA_BIND_HOST') || '127.0.0.1',
                 'mq_port' : getEnvVar('GINA_MQ_PORT') || 8125,
                 'hostname' : getEnvVar('GINA_HOSTNAME') || 'localhost',
                 'user' : process.env.USER,

package/framework/{v0.5.25 → v0.5.26}/lib/cmd/framework/set.js

@@ -108,6 +108,11 @@ function Set(opt){
                 setKeyVal('host_v4', v);
             break;
 
+            case '--bind_host':
+            case '--bind-host':
+                setKeyVal('bind_host', v);
+            break;
+
             case '--iso_short':
             case '--iso-short':
                 setKeyVal('iso_short', v);

package/framework/{v0.5.25 → v0.5.26}/lib/connector-error/src/main.js

@@ -145,10 +145,14 @@ var TRANSIENT_N1QL_CODE = {
     // honest signal for a retryable DML failure such as a CAS mismatch.
     //
     // These CODE entries are load-bearing on the connector path even where the
-    // SDK types the error: the couchbase connector's #B153 handlers forward a
-    // server-enveloped failure as a synthesized `new Error(first_error_message)`
-    // carrying only `cause` — `err.name` is 'Error' there, so TRANSIENT_NAME can
-    // never fire and this table is the sole classifier. On the raw SDK shape a
+    // SDK types the error: whenever the N1QL `cause` envelope carries server
+    // TEXT, the couchbase connector's #B153 handlers forward that failure as a
+    // synthesized `new Error(first_error_message)` carrying only `cause` —
+    // `err.name` is 'Error' there, so TRANSIENT_NAME cannot fire and this table
+    // is the sole classifier. (Only where there IS text: since the #B153
+    // residual fix an EMPTY envelope message is raw-forwarded instead, so a
+    // typed client-side timeout keeps its class name and the name rule catches
+    // it first — that is the whole point of the residual fix.) On the raw SDK shape a
     // server-side 1080 arrives typed (SDK 4.x `document_query.cxx` maps 1080 ->
     // unambiguous_timeout -> UnambiguousTimeoutError) and the name rule catches
     // it first — the 1080 entry is the belt for the envelope shape. 12008 has NO

package/framework/{v0.5.25 → v0.5.26}/lib/logger/src/containers/mq/listener.js

@@ -149,9 +149,26 @@ function MQListener(opt, cb) {
         sessions[sessionId].write( JSON.stringify(payload) +'\r\n');
     }
 
+    /**
+     * Start the MQ listener that speakers, `gina tail` and the file container
+     * connect to.
+     *
+     * @inner
+     * @param   {object}   opt          - listener options
+     * @param   {number}   opt.port     - TCP port to listen on
+     * @param   {string}   [opt.hostV4='127.0.0.1'] - bind address. NOTE the key
+     *          name: a caller passing `host` leaves this undefined, and an
+     *          undefined host makes Node bind every interface. Defaults to
+     *          loopback so an omitted key can never widen the bind.
+     * @param   {function} cb           - called once listening, or with an error
+     * @returns {void}
+     */
     function startMQListener(opt, cb) {
         var port = opt.port;
-        var host = opt.hostV4;
+        // Default to loopback when the caller omits the key, matching every
+        // sibling in this subsystem (speaker.js, tail.js, file/index.js) and
+        // ensuring an omitted option can never widen the bind to all interfaces.
+        var host = opt.hostV4 || '127.0.0.1';
         var server = net.createServer( function(conn) {//'connection' listener
 
             conn.sessionId = uuid();
@@ -211,7 +228,20 @@ function MQListener(opt, cb) {
                         i++;
                         let payload = payloads[i];
                         if ( /^\{/.test(payload) && /\}$/.test(payload)) {
-                            let pl = JSON.parse(payload);
+                            // The brace test only proves the payload LOOKS like
+                            // JSON. An unguarded parse of anything else throws
+                            // from inside this 'data' handler, which surfaces as
+                            // an uncaughtException and drops the process via
+                            // proc.js's SIGTERM path — so a single malformed
+                            // frame would end the listener for every speaker.
+                            // Skip the frame instead, mirroring bin/cmd's guard.
+                            let pl = null;
+                            try {
+                                pl = JSON.parse(payload);
+                            } catch (parseErr) {
+                                console.warn('[MQListener] ignoring malformed payload');
+                                continue;
+                            }
 
 
                             // mostly after client that acknowledeged sessionId

package/framework/{v0.5.25 → v0.5.26}/lib/mcp-http/src/main.js

@@ -13,6 +13,8 @@
  *  - Validate the `Origin` header against an allowlist (DNS rebinding
  *    mitigation per MCP spec §Security).
  *  - Enforce a static bearer token when `authToken` is configured.
+ *  - Refuse to start, token-less, once an ambient protection has been removed
+ *    (non-loopback bind, or a wildcard Origin allowlist) unless `allowInsecure`.
  *  - Emit full CORS response headers (`access-control-allow-origin` +
  *    `vary: Origin`, or `*` when wildcard allowlist is in effect).
  *
@@ -36,6 +38,41 @@ var DEFAULT_MAX_BODY_BYTES = 1024 * 1024;
 var BEARER_REALM = 'MCP';
 
 
+/**
+ * True only when `h` is unambiguously a loopback bind address, i.e. when
+ * binding it cannot make the transport reachable from another host.
+ *
+ * Deliberately fail-closed: anything this cannot positively recognise as
+ * loopback (a hostname, `0.0.0.0`, `::`, a LAN address) is treated as exposed,
+ * because guessing wrong in that direction is the expensive mistake.
+ *
+ * Recognised: `localhost`, `::1` (bracketed or bare), the whole `127.0.0.0/8`
+ * block, and IPv4-mapped forms such as `::ffff:127.0.0.1`.
+ *
+ * @param   {string} h - a bind host as handed to `server.listen()`.
+ * @returns {boolean}
+ * @inner
+ * @private
+ */
+function isLoopbackBind(h) {
+    if (typeof(h) !== 'string') return false;
+    var v = h.trim().toLowerCase();
+    if (v.charAt(0) === '[' && v.charAt(v.length - 1) === ']') {
+        v = v.substring(1, v.length - 1);
+    }
+    if (v === 'localhost' || v === '::1') return true;
+    if (v.indexOf('::ffff:') === 0) {
+        v = v.substring(7);         // IPv4-mapped IPv6 — fall through to the v4 test
+    }
+    var m = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(v);
+    if (!m) return false;
+    for (var i = 1; i <= 4; ++i) {
+        if (Number(m[i]) > 255) return false;
+    }
+    return Number(m[1]) === 127;
+}
+
+
 /**
  * Creates an HTTP transport bound to an mcp-server instance. Returns a
  * controller with `start()`, `stop()`, and `address()`.
@@ -47,9 +84,19 @@ var BEARER_REALM = 'MCP';
  * @param   {number}    [opts.maxBodyBytes]     - Cap on POST body size
  * @param   {string}    [opts.authToken]        - If set, `Authorization: Bearer <token>`
  *                                                is required on every non-OPTIONS request.
- *                                                Constant-time compared. When omitted,
- *                                                no auth is enforced (the network bind
- *                                                policy IS the security boundary).
+ *                                                Compared in constant time, sha256-hashed
+ *                                                on both sides. When omitted the transport
+ *                                                leans on its ambient protections (loopback
+ *                                                bind + Origin allowlist) and REFUSES to
+ *                                                start if either has been deliberately
+ *                                                removed — see `opts.allowInsecure`.
+ * @param   {boolean}   [opts.allowInsecure]    - Strict boolean. Set `true` to run
+ *                                                token-less even with an ambient protection
+ *                                                removed (non-loopback bind, or a wildcard
+ *                                                Origin allowlist). Assert this only when
+ *                                                access is restricted upstream — a service
+ *                                                mesh, a NetworkPolicy, or an
+ *                                                authenticating reverse proxy.
  * @param   {string[]}  [opts.allowedOrigins]   - Additional origins to accept beyond the
  *                                                built-in loopback allowlist
  *                                                (`http(s)://localhost`, `http(s)://127.0.0.1`,
@@ -87,8 +134,17 @@ function createHttpTransport(opts) {
     var authToken     = (typeof(opts.authToken) === 'string' && opts.authToken.length) ? opts.authToken : null;
     var extraOrigins  = Array.isArray(opts.allowedOrigins) ? opts.allowedOrigins.slice() : [];
     var originWildcard = (extraOrigins.indexOf('*') !== -1);
+    var allowInsecure = (opts.allowInsecure === true);
     var onError       = (typeof(opts.onError) === 'function') ? opts.onError : function() {};
 
+    // Digest the configured token ONCE, here, rather than per request: the
+    // compare in `isAuthed` then runs over two fixed-length (32-byte) buffers,
+    // so it can neither throw nor leak the token's length. Mirrors the
+    // boot-precomputed key hashes in `lib/authz-gate` (`verifyMachineToken`).
+    var authTokenHash = authToken
+        ? crypto.createHash('sha256').update(authToken, 'utf8').digest()
+        : null;
+
     var httpServer = null;
 
 
@@ -133,9 +189,13 @@ function createHttpTransport(opts) {
 
     /**
      * True when the request carries a valid bearer (or no token is configured).
-     * Constant-time compares the presented token to the configured one.
-     * Length mismatch short-circuits to false WITHOUT calling
-     * `crypto.timingSafeEqual` — that API throws on length mismatch.
+     *
+     * Both sides are sha256-hashed before the constant-time compare, so the two
+     * buffers are always 32 bytes. That removes the length short-circuit this
+     * used to need — comparing the raw tokens meant returning early on a length
+     * mismatch (`timingSafeEqual` throws on unequal lengths), which leaked the
+     * configured token's length through response timing. The try/catch is kept
+     * as the house idiom even though two same-length digests cannot throw.
      *
      * @private
      */
@@ -144,15 +204,40 @@ function createHttpTransport(opts) {
         var header = req.headers['authorization'] || '';
         var m = /^Bearer\s+(.+)$/i.exec(header);
         if (!m) return false;
-        var presented = m[1].trim();
-        var expected  = Buffer.from(authToken, 'utf8');
-        var actual    = Buffer.from(presented,  'utf8');
-        if (expected.length !== actual.length) return false;
-        try { return crypto.timingSafeEqual(expected, actual); }
+        var presented     = m[1].trim();
+        var presentedHash = crypto.createHash('sha256').update(presented, 'utf8').digest();
+        try { return crypto.timingSafeEqual(presentedHash, authTokenHash); }
         catch (e) { return false; }
     }
 
 
+    /**
+     * Describes the ambient protection the operator has removed, when running
+     * without a bearer token — or `null` when the transport is adequately
+     * protected (or `allowInsecure` waives the requirement).
+     *
+     * Two protections make a token-less transport defensible, and losing EITHER
+     * is enough to need one:
+     *  - the loopback bind, which keeps other hosts out entirely;
+     *  - the Origin allowlist, which is the only thing standing between a
+     *    loopback-bound server and a DNS-rebinding attack driven from any web
+     *    page (the bind does not help there — the browser is already local).
+     *
+     * @returns {string|null} the reason, phrased for an operator-facing error.
+     * @private
+     */
+    function describeExposure() {
+        if (authToken || allowInsecure) return null;
+        if (!isLoopbackBind(host)) {
+            return 'it is bound to the non-loopback address `'+ host +'`';
+        }
+        if (originWildcard) {
+            return 'the Origin allowlist is disabled (`allowedOrigins: ["*"]`)';
+        }
+        return null;
+    }
+
+
     /**
      * Merges CORS response headers into a base header bag. Safe to call even
      * when there is no `Origin` on the request — returns the base bag unchanged
@@ -510,6 +595,12 @@ function createHttpTransport(opts) {
      * resolved { host, port, family } — `port` is the OS-assigned port when
      * `opts.port` was 0.
      *
+     * Also rejects, BEFORE binding, when the transport would be exposed without
+     * a bearer token (see `describeExposure`). Refusing here rather than
+     * answering 401 per request is the framework's house answer for a security
+     * control that would otherwise sit silently inert: nothing ever listens, so
+     * there is no window in which an unauthenticated port is reachable.
+     *
      * @returns {Promise<{host: string, port: number, family: string}>}
      */
     function start() {
@@ -517,6 +608,14 @@ function createHttpTransport(opts) {
             if (httpServer) {
                 return reject(new Error('start: transport already started'));
             }
+            var exposure = describeExposure();
+            if (exposure) {
+                return reject(new Error(
+                    'start: refusing to listen without a bearer token because '+ exposure +'. '
+                  + 'Configure a token, or set `allowInsecure` to assert that access is '
+                  + 'restricted upstream (service mesh, NetworkPolicy, authenticating proxy).'
+                ));
+            }
             var server = http.createServer(handleHttpRequest);
             var onListenError = function(err) { reject(err); };
             server.once('error', onListenError);

package/framework/{v0.5.25 → v0.5.26}/lib/merge/src/main.js

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

package/framework/{v0.5.25 → v0.5.26}/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gina-framework",
-  "version": "0.5.25",
+  "version": "0.5.26",
   "dependencies": {
     "@rhinostone/busboy": "^1.6.1",
     "@rhinostone/swig": "^2.7.2",

package/gna.js

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