gina 0.6.3 → 0.6.4

package/framework/{v0.6.3 → v0.6.4}/lib/cmd/secrets/help.txt

@@ -2,8 +2,9 @@
   Usage: gina secrets:<action> [options]
 
   Introspect the ${secret:KEY} placeholders your bundle configs require.
-  Read-only: these commands never resolve a secret, never read a value,
-  and never write anything.
+  Read-only: these commands never write anything, and never print a secret
+  value. `check` reads the sources a bundle would resolve from, in order to
+  report presence — it does not resolve a placeholder.
 
   Actions:
 
@@ -34,9 +35,20 @@
                                  wins) so the report shows the EFFECTIVE keys
                                  that scope's deploy requires. Scope must be
                                  registered (see `gina scope:list`).
-    --env-file=<path>            (check) Validate against a `.env`-style file's
-                                 vars instead of the live process.env — e.g. a
-                                 decrypted SOPS export or a CI-exported env.
+                                 (check) Also supplies ${scope} when resolving a
+                                 `settings.secrets.file` path. That token alone
+                                 falls back to the project's default scope, so a
+                                 scope-templated chain resolves without the flag;
+                                 the config_<scope>/ overlay still needs it
+                                 explicitly and is never applied by default.
+    --env=<env>                  (check) Which env's block to read `homedir`
+                                 from when resolving a `settings.secrets.file`
+                                 path. Defaults to the project's default env.
+    --env-file=<path>            (check) Stand in for the live process.env —
+                                 e.g. a decrypted SOPS export or a CI-exported
+                                 env. It occupies the ENVIRONMENT tier, which
+                                 outranks the file tier, so it still wins over
+                                 a declared `settings.secrets.file`.
 
   Examples:
 
@@ -67,5 +79,17 @@
       it cannot introspect an already-running bundle.
     - A key counts as SET only when it is a non-empty string, the same
       condition under which the bundle would start without a secret error.
+    - `check` looks in the same two tiers the runtime does, in the same
+      order: the environment first, then any file the bundle declares in
+      `settings.secrets.file`. The report lists that chain per bundle, marks
+      each layer `loaded`/`ABSENT`, and names the tier each key came from —
+      so a SET sourced from a plaintext file on this disk is never mistaken
+      for one your deployment will inject.
+    - `${scope}` and `${env}` inside a declared path are LAUNCH-time values:
+      the runtime reads NODE_SCOPE / NODE_ENV from whatever starts the
+      bundle, which this process cannot see. The report names the values it
+      assumed. If a token cannot be resolved at all, the file tier is
+      skipped and said so — that can only make this gate stricter than the
+      runtime, never laxer.
 
   Reference: https://gina.io/docs/guides/secrets

package/framework/v0.6.4/lib/loading-state/package.json

@@ -0,0 +1,7 @@
+{
+    "name": "gina-lib-loading-state",
+    "version": "1.0.0",
+    "description": "Framework-owned loading state for submit-like triggers (data-gina-loading)",
+    "main": "src/main",
+    "license": "MIT"
+}

package/framework/v0.6.4/lib/loading-state/src/main.js

@@ -0,0 +1,366 @@
+'use strict';
+/**
+ * This file is part of the gina package.
+ * Copyright (c) 2009-2026 Rhinostone <contact@gina.io>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+/**
+ * @module lib/loading-state
+ * @description Framework-owned loading state for submit-like triggers. Works in
+ * Node.js (CommonJS) and browser (AMD / GFF) contexts.
+ *
+ * A submit-like trigger — `<button type="submit">`, `<input type="submit">` or an
+ * `<a data-gina-form-submit>` — carries `data-gina-loading="true"` for exactly as
+ * long as the action it started is running, and `"false"` once that action
+ * completes OR is interrupted. Consumers style the running state with CSS.
+ *
+ * The module owns three things and no more: resolving the configured attribute
+ * NAME, writing the two values, and walking a click target up to the trigger that
+ * actually owns it. It holds NO state — the caller decides which element is armed
+ * and where to remember it, so the validator, popin and link plugins can share one
+ * implementation without sharing a registry.
+ *
+ * ## The `"false"` value is deliberate, and it constrains readers
+ *
+ * `disarm()` writes the STRING `"false"`; it does not remove the attribute. That
+ * diverges on purpose from the form-scoped `data-gina-form-loading`, which #B175
+ * changed from `setAttribute(..., false)` to `removeAttribute()` precisely because
+ * `"false"` is attribute-PRESENT and therefore truthy for a presence check.
+ *
+ * The consequence is a hard rule for every reader, in the framework and in
+ * consumer CSS alike: **match on the VALUE, never on presence**. Use
+ * `[data-gina-loading="true"]`, never a bare `[data-gina-loading]`, and in JS use
+ * {@link module:lib/loading-state~isArmed} rather than reading the attribute
+ * directly. A bare presence selector matches a disarmed trigger and pins the
+ * loading style on forever.
+ *
+ * ## Configuring the attribute name
+ *
+ * The name is read from `gina.config.loadingAttribute`, lazily, at every call —
+ * `gina.config` is populated after the bundle loads (via `setOptions`), so a value
+ * captured at module-definition time would be stale. A project already built on
+ * `data-loading` opts in with:
+ *
+ * ```html
+ * <script src="/js/vendor/gina/gina.min.js"
+ *         data-gina-config="{ loadingAttribute: 'data-loading' }"></script>
+ * ```
+ *
+ * or `gina.setOptions({ loadingAttribute: 'data-loading' })`. There is no
+ * auto-detection: a DOM probe reads nothing at rest (the attribute only exists
+ * while something is loading) and a stylesheet probe races late-loaded sheets and
+ * throws on cross-origin ones. Configuration is explicit by design.
+ *
+ * @example
+ * var loadingState = require('lib/loading-state');
+ *
+ * var $trigger = loadingState.resolveTrigger(event.target, $form);
+ * loadingState.arm($trigger);      // data-gina-loading="true"
+ * // ... the action runs, then settles, errors, times out or is rejected ...
+ * loadingState.disarm($trigger);   // data-gina-loading="false"
+ */
+
+/**
+ * Loading-state factory — returns the stateless API object.
+ * Exported as the module itself via `module.exports = LoadingState()`.
+ *
+ * @function LoadingState
+ * @returns {object} The `{ arm, disarm, isArmed, getAttributeName, resolveTrigger, DEFAULT_ATTRIBUTE }` API
+ *
+ * @memberof module:lib
+ * @author  Rhinostone <contact@gina.io>
+ * @api     Public
+ */
+function LoadingState() {
+
+    /**
+     * The attribute written when no `gina.config.loadingAttribute` override is set.
+     *
+     * @constant {string}
+     * @inner
+     */
+    var DEFAULT_ATTRIBUTE = 'data-gina-loading';
+
+    /**
+     * The value written by `arm()`.
+     *
+     * @constant {string}
+     * @inner
+     */
+    var ARMED = 'true';
+
+    /**
+     * The value written by `disarm()`. NOT `removeAttribute` — see the module
+     * description for why, and for the presence-check rule it imposes on readers.
+     *
+     * @constant {string}
+     * @inner
+     */
+    var DISARMED = 'false';
+
+    /**
+     * How many ancestors `resolveTrigger()` will climb before giving up. A submit
+     * trigger is a direct child of its form in every realistic markup, so this is a
+     * runaway guard rather than a real limit — a detached or cyclic node can not
+     * spin the loop.
+     *
+     * @constant {number}
+     * @inner
+     */
+    var MAX_DEPTH = 10;
+
+    /**
+     * isNode
+     *
+     * True when `$el` can carry attributes. Guards every public entry point so a
+     * `null`, a text node, a `window` or a plain object is a silent no-op rather
+     * than a thrown TypeError inside an event handler.
+     *
+     * @param {object} $el - candidate element
+     *
+     * @returns {boolean} true when `$el` exposes the attribute API
+     *
+     * @example
+     * isNode(document.querySelector('button')); // true
+     * isNode(null);                             // false
+     *
+     * @inner
+     */
+    var isNode = function($el) {
+        return !!(
+            $el
+            && typeof($el.setAttribute) == 'function'
+            && typeof($el.getAttribute) == 'function'
+        );
+    };
+
+    /**
+     * isSubmitTrigger
+     *
+     * True when `$el` is an element a user submits a form WITH. Mirrors the shapes
+     * the validator's click proxy already recognises: a `button`/`input` whose type
+     * is `submit`, or an anchor carrying `data-gina-form-submit`.
+     *
+     * @param {object} $el - candidate element
+     *
+     * @returns {boolean} true when `$el` is a submit-like trigger
+     *
+     * @example
+     * isSubmitTrigger($button); // true for <button type="submit">
+     * isSubmitTrigger($span);   // false
+     *
+     * @inner
+     */
+    var isSubmitTrigger = function($el) {
+        if ( !isNode($el) || !$el.tagName ) {
+            return false;
+        }
+        if ( /^(button|input)$/i.test($el.tagName) && /^submit$/i.test($el.type || '') ) {
+            return true;
+        }
+        if ( /^a$/i.test($el.tagName) && $el.getAttribute('data-gina-form-submit') != null ) {
+            return true;
+        }
+        return false;
+    };
+
+    /**
+     * getAttributeName
+     *
+     * Resolves the attribute name to write. Reads `gina.config.loadingAttribute`
+     * LAZILY on every call: `gina.config` is populated after the bundle loads, so a
+     * value captured once at definition time would always be the default. Falls
+     * back to `data-gina-loading` when unset, empty or not a string.
+     *
+     * @returns {string} the configured attribute name, or `data-gina-loading`
+     *
+     * @example
+     * getAttributeName();                                  // 'data-gina-loading'
+     * gina.setOptions({ loadingAttribute: 'data-loading' });
+     * getAttributeName();                                  // 'data-loading'
+     *
+     * @api Public
+     */
+    var getAttributeName = function() {
+        if (
+            typeof(gina) != 'undefined' && gina && gina.config
+            && typeof(gina.config.loadingAttribute) == 'string'
+            && gina.config.loadingAttribute !== ''
+        ) {
+            return gina.config.loadingAttribute;
+        }
+        return DEFAULT_ATTRIBUTE;
+    };
+
+    /**
+     * arm
+     *
+     * Marks `$el` as running by writing `<attribute>="true"`. Idempotent — arming an
+     * already-armed trigger rewrites the same value. A non-element is a no-op.
+     *
+     * @param {object} $el - the trigger to mark (see `resolveTrigger`)
+     *
+     * @returns {boolean} true when the attribute was written
+     *
+     * @example
+     * arm($button); // $button now carries data-gina-loading="true"
+     *
+     * @api Public
+     */
+    var arm = function($el) {
+        if ( !isNode($el) ) {
+            return false;
+        }
+        $el.setAttribute(getAttributeName(), ARMED);
+        return true;
+    };
+
+    /**
+     * disarm
+     *
+     * Releases `$el` by writing `<attribute>="false"`. Called on EVERY terminal
+     * outcome — settled, errored, timed out, aborted, rate-limited and
+     * validation-rejected — so a trigger can not stay visually loading after its
+     * action stopped. Idempotent; a non-element is a no-op.
+     *
+     * Writes `"false"` rather than removing the attribute; see the module
+     * description for the reasoning and the presence-check rule it imposes.
+     *
+     * @param {object} $el - the trigger to release
+     *
+     * @returns {boolean} true when the attribute was written
+     *
+     * @example
+     * disarm($button); // $button now carries data-gina-loading="false"
+     *
+     * @api Public
+     */
+    var disarm = function($el) {
+        if ( !isNode($el) ) {
+            return false;
+        }
+        $el.setAttribute(getAttributeName(), DISARMED);
+        return true;
+    };
+
+    /**
+     * isArmed
+     *
+     * True only when `$el` is currently marked as running. Compares the VALUE
+     * against `"true"` — never tests presence, because a disarmed trigger still
+     * carries the attribute with `"false"`. Use this instead of reading the
+     * attribute directly.
+     *
+     * @param {object} $el - the trigger to inspect
+     *
+     * @returns {boolean} true when `$el` carries `<attribute>="true"`
+     *
+     * @example
+     * arm($button);    isArmed($button); // true
+     * disarm($button); isArmed($button); // false — attribute present, value "false"
+     *
+     * @api Public
+     */
+    var isArmed = function($el) {
+        if ( !isNode($el) ) {
+            return false;
+        }
+        return $el.getAttribute(getAttributeName()) === ARMED;
+    };
+
+    /**
+     * resolveTrigger
+     *
+     * Walks `$el` up to the submit trigger that owns it, so the state lands on the
+     * control the user perceives as the button rather than on whatever inner node
+     * happened to receive the click. `<button type="submit"><span>Save</span></button>`
+     * clicked on the label yields the `button`, not the `span`.
+     *
+     * Returns `$el` itself when no submit-like ancestor is found, so a caller that
+     * already knows it is handling a submit still gets a usable element. Stops at
+     * the boundary element (typically the form), at `form`/`body`/`html`, or after
+     * `MAX_DEPTH` hops.
+     *
+     * ## Recognising a non-submit trigger (`isTrigger`)
+     *
+     * The default predicate recognises submit-like controls only — a `button` or
+     * `input` of type `submit`, or an `a[data-gina-form-submit]`. That is what the
+     * validator needs and nothing else. Other plugins arm elements this module has
+     * no business knowing about: link arms `a[data-gina-link]`, popin arms
+     * `a[data-gina-dialog]`. Pass `isTrigger` to say what counts as YOUR trigger.
+     *
+     * Without it the climb finds no match, breaks at `form`/`body`/`html`, and
+     * returns the ORIGINAL `$el` — so a click on the `<span>` inside
+     * `<a data-gina-link><span>Go</span></a>` would arm the span and leave the
+     * anchor unstyled.
+     *
+     * The predicate lives with the caller deliberately rather than being folded
+     * into the default: this module owns the WALK, each plugin owns its own notion
+     * of a trigger. Folding plugin attribute names in here would also couple the
+     * module to the popin deprecation/alias work, which changes which attributes
+     * are honoured over time.
+     *
+     * @param {object} $el - the clicked element (`event.target`)
+     * @param {object} [$boundary] - element to stop at, usually the `<form>`
+     * @param {function} [isTrigger] - `($node) => boolean`; defaults to the
+     *   submit-like predicate. Ignored when not a function. A predicate that
+     *   THROWS is deliberately not caught: every caller is framework code, so
+     *   swallowing would hide a framework bug behind a silently unarmed trigger.
+     *
+     * @returns {object} the owning trigger, or `$el`, or `null` when `$el` is not an element
+     *
+     * @example
+     * // <button type="submit"><span>Save</span></button>
+     * resolveTrigger(event.target, $form); // the <button>, even when the <span> was clicked
+     *
+     * @example
+     * // <a data-gina-link><span>Go</span></a> — the span was clicked
+     * resolveTrigger(event.target, null, function($n) {
+     *     return /^a$/i.test($n.tagName) && $n.getAttribute('data-gina-link') != null;
+     * }); // the <a>, not the <span>
+     *
+     * @api Public
+     */
+    var resolveTrigger = function($el, $boundary, isTrigger) {
+        if ( !isNode($el) ) {
+            return null;
+        }
+        var matches = ( typeof(isTrigger) == 'function' ) ? isTrigger : isSubmitTrigger;
+        var $node = $el;
+        var depth = 0;
+        while ( isNode($node) && depth < MAX_DEPTH ) {
+            if ( matches($node) ) {
+                return $node;
+            }
+            if ( $boundary && $node === $boundary ) {
+                break;
+            }
+            if ( $node.tagName && /^(form|body|html)$/i.test($node.tagName) ) {
+                break;
+            }
+            $node = $node.parentNode;
+            ++depth;
+        }
+        return $el;
+    };
+
+    return {
+        'DEFAULT_ATTRIBUTE' : DEFAULT_ATTRIBUTE,
+        'getAttributeName'  : getAttributeName,
+        'arm'               : arm,
+        'disarm'            : disarm,
+        'isArmed'           : isArmed,
+        'resolveTrigger'    : resolveTrigger
+    };
+}
+
+if ( ( typeof(module) !== 'undefined' ) && module.exports ) {
+    // Publish as node.js module
+    module.exports = LoadingState()
+} else if ( typeof(define) === 'function' && define.amd) {
+    // Publish as AMD module
+    define('lib/loading-state', function() { return LoadingState() })
+}

package/framework/{v0.6.3 → v0.6.4}/lib/logger/src/containers/mq/listener.js

@@ -174,6 +174,29 @@ function MQListener(opt, cb) {
             conn.sessionId = uuid();
             // conn.request = 'report'; // by default
             sessions[conn.sessionId] = conn;
+
+            // #B279 — a speaker that goes away abruptly (a CLI that finished or
+            // was killed) leaves this connection socket registered but broken.
+            // The next write to it — the handshake below, or `self.report()`'s
+            // `sessions[sessionId].write()` — then raises EPIPE/ECONNRESET on the
+            // socket, and with no 'error' listener node THROWS it: the whole
+            // process dies. That is not theoretical — it is how a `bundle:add`
+            // died mid-command on CI, before writing ports.reverse.json, because
+            // every `bin/cli` invocation starts this listener on the shared MQ
+            // port and parallel test files speak to each other's listener.
+            // `server.on('error')` below does NOT cover this: every accepted
+            // connection is its own EventEmitter.
+            // A departed client is normal TCP lifecycle rather than a listener
+            // fault (`lib/proc.js` reaches the same conclusion for the server
+            // socket), so drop the session and carry on. Dropping matters: an
+            // abruptly-killed peer may never emit 'end', which is what otherwise
+            // clears `sessions` — leaving a dead socket for the next write.
+            // Registered BEFORE the handshake write, which is itself a site.
+            conn.on('error', function(err) {
+                delete sessions[this.sessionId];
+                console.debug('[MQListener] (error) speaker `'+ this.sessionId +'` dropped: '+ (err.code || err.message));
+            });
+
             conn.write(JSON.stringify({ sessionId: conn.sessionId }) +'\r\n' );
 
             //feedback.

package/framework/{v0.6.3 → v0.6.4}/lib/logger/src/containers/mq/speaker.js

@@ -82,6 +82,24 @@ function MQSpeaker(opt, loggers, cb) {
     }
 
 
+    /**
+     * Opens the speaker's connection to the MQ listener.
+     *
+     * The socket is `unref`'d: a logging transport must never be the reason a
+     * process stays alive. Processes that legitimately run long hold the event
+     * loop open by their own means — a bundle keeps it alive with its HTTP
+     * server (`core/server.js` owns the single `listen()` call for both
+     * engines) — so unref'ing costs them nothing while it stops the speaker
+     * from outliving its host.
+     *
+     * @inner
+     * @param {object} opt - Logger options; `mqPort`/`hostV4`/`bindHost` are read here.
+     * @param {function} [cb] - Called `(false, client)` on connect, `(err)` on error.
+     * @returns {object} The connected (unref'd) net.Socket.
+     *
+     * @example
+     * startMQSpeaker({ mqPort: 8125, hostV4: '127.0.0.1' }, function (err, client) { });
+     */
     function startMQSpeaker(opt, cb) {
         var port = opt.mqPort || 8125;// jshint ignore:line
         // #B160 — the MQ listener binds `bind_host` (loopback by default):
@@ -103,6 +121,15 @@ function MQSpeaker(opt, loggers, cb) {
                 cb(false, client)
             }
         });
+        // #B276 — the logger is a load-time singleton (`lib/index.js` requires it
+        // eagerly, `main.js` invokes `Logger()` at module scope), so this socket is
+        // opened by the mere act of requiring the framework — including on a boot
+        // that is about to throw for want of a bundle context. Without unref, that
+        // documented throw becomes unrecoverable: the caller catches the error and
+        // the process still cannot exit, because the socket keeps the loop alive.
+        // Only bites when something is actually listening on the MQ port; with
+        // nothing there the connection is refused and the handle closes itself.
+        client.unref();
         client.on('error', (data) => {
             var err = data.toString();
             if (cb) {

package/framework/v0.6.4/lib/secrets/src/backends/file.js

@@ -0,0 +1,180 @@
+'use strict';
+/**
+ * @module lib/secrets/backends/file
+ * @description Backend that layers one or more `.env`-style files *underneath*
+ * the environment.
+ *
+ * **A NON-EMPTY environment value always wins.** A value present in
+ * `process.gina` / `process.env` is returned even when a file also defines the
+ * key. That ordering is deliberate and is the opposite of what `.env`-file
+ * tooling usually does: every production mechanism for delivering a secret to a
+ * gina bundle — a Kubernetes `envFrom: secretRef`, an ECS task-definition secret,
+ * `sops exec-env`, a CI-exported variable — arrives through the environment.
+ * If a file won, a stale plaintext file baked into an image would silently
+ * shadow the secret the platform injected, and the bundle would run with the
+ * wrong credential while looking perfectly healthy. Making the file the
+ * *fallback* means it can only ever fill a gap, never override a deployment.
+ *
+ * **The "non-empty" qualifier is load-bearing, and deliberately NOT a refusal**
+ * (#B268). A variable that is SET but EMPTY is treated as absent, so the file
+ * tier fills it. That is what makes the common local shape work: Docker Compose
+ * `environment: ["X=${X}"]` with the outer `X` unset puts an empty-but-SET `X`
+ * into the container (measured), and refusing there would break setups that are
+ * working today. But the same shape also arises when an entrypoint's
+ * `export X="$(fetch …)"` FAILS — and there the file silently supplying a stale
+ * value is exactly the shadowing this ordering exists to prevent. Since the two
+ * are indistinguishable from inside the process, the file tier does not guess:
+ * it fills the gap and WARNS (see `resolve`), so the dangerous case is visible
+ * without the benign one becoming fatal.
+ *
+ * Files are layered in declaration order, later entries winning, so a caller
+ * can express `["<base>", "<per-scope>"]` and have the scope-specific file
+ * override shared defaults. A file that does not exist contributes nothing and
+ * is not an error — a project may legitimately ship a base file and add the
+ * per-scope one only on some targets. A file that EXISTS but cannot be read is
+ * a different matter and is fatal (#B267): silently skipping it would drop that
+ * chain onto the shared base file, i.e. run the bundle on the wrong credential
+ * with no signal at all.
+ *
+ * This backend does NOT decrypt. Pointing it at an encrypted file yields
+ * ciphertext, silently. For SOPS / Vault / KMS, keep decrypting at the
+ * container entrypoint so the values land in the environment, which this
+ * backend already prefers.
+ */
+
+var envBackend = require('./env');
+var envFile    = require('../env-file');
+
+/**
+ * Is `key` present in one of the environment tiers but carrying an EMPTY value?
+ *
+ * The env backend cannot answer this: it treats empty as unset by contract and
+ * throws either way, so a caller that catches its throw knows only "not usable",
+ * never "not there". This reads the raw slots to recover the distinction — used
+ * solely to decide whether falling back to the file tier deserves a warning
+ * (#B268), never to change which value is returned.
+ *
+ * Both tiers are checked because `getEnvVar()` itself rejects `''`
+ * (`utils/helper.js` guards on `process.gina[key] != ''`), so an empty value in
+ * the framework environment is invisible through the normal accessor.
+ *
+ * @inner
+ * @private
+ * @param {string} key - Placeholder key, e.g. `'DB_PASSWORD'`
+ * @returns {boolean} `true` only when a tier holds `key` as an empty string
+ */
+function isEnvPresentButEmpty(key) {
+    if (
+        typeof process.gina === 'object' && process.gina !== null &&
+        typeof process.gina[key] === 'string' && process.gina[key] === ''
+    ) {
+        return true;
+    }
+    return (typeof process.env[key] === 'string' && process.env[key] === '');
+}
+
+/**
+ * Build a backend that reads the environment first and the given files second.
+ *
+ * @memberof module:lib/secrets/backends/file
+ * @function build
+ * @param {string[]} paths - Absolute, already-substituted file paths, lowest precedence first
+ * @returns {{resolve: function(string): string}} A backend honouring the `lib/secrets` contract
+ * @throws {Error} When a declared path EXISTS but cannot be read (`EACCES`, `EISDIR`, …).
+ *   A genuinely absent path (`ENOENT`) is not an error and contributes nothing (#B267).
+ *
+ * @example
+ * var backend = build(['/home/u/.myproject/secrets.env',
+ *                      '/home/u/.myproject/production/secrets.env']);
+ * backend.resolve('DB_PASSWORD');
+ * // non-empty env value if set; else the production file's; else the base file's;
+ * // else throws Error('Secret resolution failed')
+ *
+ * @example
+ * // An unreadable layer refuses at BUILD time rather than degrading silently:
+ * // chmod 000 /home/u/.myproject/production/secrets.env
+ * build(['/home/u/.myproject/secrets.env',
+ *        '/home/u/.myproject/production/secrets.env']);
+ * // → throws '`settings.secrets.file` names a file that exists but cannot be read: … (EACCES)'
+ */
+function build(paths) {
+    // Layer eagerly, once per config-load cycle, rather than statting on every
+    // key: resolution walks the whole config and would otherwise re-read the
+    // same files for each placeholder.
+    var merged = Object.create(null);
+    for (var i = 0; i < paths.length; i++) {
+        var res = envFile.readEnvFile(paths[i]);
+
+        // #B267 — a path that EXISTS but cannot be read is an operator error, not
+        // an absent layer. Skipping it silently drops a `["<base>", "<per-scope>"]`
+        // chain onto the base file, so the bundle boots healthily on the SHARED
+        // credential. Refuse instead: the caller (core/config.js::loadBundleConfig)
+        // reports this as a config error and the boot stops with the path named.
+        if (!res.found && res.code !== 'ENOENT') {
+            throw new Error('`settings.secrets.file` names a file that exists but cannot be read: '
+                + paths[i] + ' (' + res.code + ')');
+        }
+
+        // Name each layer and whether it was found. A misresolved path is
+        // otherwise indistinguishable from a file that simply lacks the key:
+        // both surface as the same fail-closed error, several frames away.
+        try {
+            console.debug('[secrets][file] ' + (res.found ? 'loaded ' : 'ABSENT ')
+                + paths[i] + (res.found ? ' (' + Object.keys(res.map).length + ' keys)' : ''));
+        } catch (noLogger) { /* logger not up yet — diagnostics are best-effort */ }
+        if (!res.found) continue;            // absent file: contributes nothing, not an error
+        for (var key in res.map) {
+            merged[key] = res.map[key];      // later path wins
+        }
+    }
+
+    return {
+        resolve: function (key) {
+            // Environment tiers first — delegate to the env backend rather than
+            // re-implementing its two-tier `getEnvVar` -> `process.env` read
+            // (#B156), so the two can never disagree about what "set" means.
+            // It throws on miss, which here means "not in the environment".
+            try {
+                return envBackend.resolve(key);
+            } catch (notInEnv) {
+                // fall through to the file layer
+            }
+
+            var value = merged[key];
+            if (typeof value === 'string' && value !== '') {
+                // #B268 — the env backend reports "set but empty" and "absent"
+                // identically, so reaching here does not say which happened. When
+                // it was the former, the file is about to override a value the
+                // environment DID carry, which is the one case this ordering is
+                // meant to make impossible. Warn (never fatal — see the module
+                // header for why refusing would break Compose-style passthrough),
+                // at `warn` so it survives the default `info` log hierarchy, and
+                // name only the KEY: the message reaches user-facing surfaces.
+                if (isEnvPresentButEmpty(key)) {
+                    try {
+                        console.warn('[secrets][file] `' + key + '` is present but EMPTY in the'
+                            + ' environment; falling back to the file tier. If the environment was'
+                            + ' meant to supply it, whatever exports it produced an empty value.');
+                    } catch (noLogger) { /* logger not up yet — diagnostics are best-effort */ }
+                }
+                return value;
+            }
+
+            // Same failure shape as the env backend: the message never names
+            // the key (it reaches user-facing surfaces), while the key rides
+            // on a non-enumerable property for debug logging.
+            var err = new Error('Secret resolution failed');
+            Object.defineProperty(err, '_ginaSecretKey', {
+                value: key,
+                enumerable: false,
+                configurable: true,
+                writable: true
+            });
+            throw err;
+        }
+    };
+}
+
+module.exports = {
+    build: build
+};