gina 0.6.3 → 0.6.4

package/framework/v0.6.4/lib/secrets/src/env-file.js

@@ -0,0 +1,220 @@
+'use strict';
+/**
+ * @module lib/secrets/env-file
+ * @description `.env`-style parsing, shared so that every reader of a given
+ * file agrees on what it means.
+ *
+ * Two consumers exist today and they answer different questions about the
+ * same bytes: the `gina secrets:check` CLI handler asks *"would a bundle
+ * started here resolve its placeholders?"*, and a file-backed secrets backend
+ * asks *"what value does this key have?"*. If those two parsed differently —
+ * on a quoted value, an `export ` prefix, a CRLF line ending — `secrets:check`
+ * could report a clean bill of health for a file the runtime then reads
+ * differently. Keeping one implementation makes that class of disagreement
+ * impossible rather than merely unlikely.
+ *
+ * Deliberately minimal: no interpolation, no multi-line values, no `.env`
+ * dialect extensions. It targets the format a POSIX shell would `source` —
+ * which is how the documented container-entrypoint pattern
+ * (`set -a; . secrets.env; set +a`) populates the environment — and agrees
+ * with a real shell on the shapes a secrets file actually uses: quoted and
+ * unquoted values, `export ` prefixes, blank lines, whole-line comments, and
+ * (since #B269) trailing `#` comments.
+ *
+ * It is NOT a shell, and two divergences remain, both measured against `sh`:
+ * `KEY = value` (a shell errors, trying to execute `KEY`; this accepts it and
+ * trims), and `KEY="a"b"` (a shell concatenates to `ab`; this yields `a"b`).
+ * Neither warrants a tokeniser here — but do not restate this module as
+ * "whatever a POSIX shell does", because for those two shapes it is not.
+ * Quote any value whose meaning could depend on shell word-splitting.
+ */
+
+var fs = require('fs');
+
+/**
+ * Parse `.env`-style content into a flat `KEY -> value` map.
+ *
+ * Recognised per line: blank lines and whole-line `#` comments are skipped; a
+ * leading `export ` is stripped; the key is everything before the FIRST `=`; a
+ * line with no `=` is skipped entirely. A TRAILING `#` comment is stripped when
+ * the `#` is preceded by whitespace and sits outside quotes (#B269) — so
+ * `PW=abc # note` is `abc`, while `PW=abc#def` and `PW="abc # in"` keep their
+ * hash. A value wrapped in matching single or double quotes is unquoted, and
+ * that still applies after a trailing comment is removed (`PW="abc" # note` is
+ * `abc`, not `"abc"`). Keys and values are trimmed. Later duplicate keys
+ * overwrite earlier ones, matching shell `source` semantics.
+ *
+ * The returned map is created with a `null` prototype, so a key such as
+ * `constructor` or `__proto__` is an ordinary entry rather than an inherited
+ * member — a plain `{}` would make `map.constructor` truthy for every file.
+ *
+ * @memberof module:lib/secrets/env-file
+ * @function parseEnv
+ * @param {string} raw - The file's contents
+ * @returns {Object<string,string>} Parsed key/value map (null-prototype)
+ *
+ * @example
+ * parseEnv('# db\nexport DB_PW=s3cr3t\nAPI_KEY="quoted"\nEMPTY=\nNOEQ\n');
+ * // → { DB_PW: 's3cr3t', API_KEY: 'quoted', EMPTY: '' }
+ * // `NOEQ` is absent: no `=`, so the line is skipped.
+ */
+/**
+ * Truncate a raw (un-trimmed) value at an inline `#` comment, the way a POSIX
+ * shell would when `source`-ing the same line.
+ *
+ * Two conditions must BOTH hold for a `#` to start a comment, and each exists
+ * because dropping it corrupts a legitimate secret (all cases measured against
+ * a real `sh` — see #B269):
+ *
+ * - **Preceded by whitespace.** `PW=abc#def` is the literal `abc#def` to a
+ *   shell, so a `#` that directly follows the `=` or a non-blank character is
+ *   an ordinary character. This is why the raw, UN-trimmed value is required:
+ *   after trimming, `PW= # c` and `PW=#c` both start with `#` and become
+ *   indistinguishable, yet the shell reads them as `''` and `'#c'`.
+ * - **Outside quotes.** `PW="abc # inside"` keeps its hash; quoting is a
+ *   complete escape hatch for a secret that genuinely contains ` #`.
+ *
+ * @memberof module:lib/secrets/env-file
+ * @inner
+ * @private
+ * @param {string} raw - The value as it appears after the first `=`, un-trimmed
+ * @returns {string} `raw` truncated at the comment, or `raw` unchanged
+ *
+ * @example
+ * stripInlineComment('abc # note');      // → 'abc '
+ * stripInlineComment('abc#def');         // → 'abc#def'   (no leading space)
+ * stripInlineComment('"a # b" # note');  // → '"a # b" '  (first hash quoted)
+ * stripInlineComment('#literal');        // → '#literal'  (directly after `=`)
+ */
+function stripInlineComment(raw) {
+    var quote = null;
+    for (var i = 0; i < raw.length; i++) {
+        var ch = raw[i];
+        if (quote) {
+            if (ch === quote) {
+                quote = null;
+            }
+            continue;
+        }
+        if (ch === '"' || ch === "'") {
+            quote = ch;
+            continue;
+        }
+        if (ch === '#' && i > 0 && /\s/.test(raw[i - 1])) {
+            return raw.slice(0, i);
+        }
+    }
+    return raw;
+}
+
+function parseEnv(raw) {
+    var map = Object.create(null);
+    if (typeof raw !== 'string') {
+        return map;
+    }
+    var lines = raw.split(/\r?\n/);
+    for (var i = 0; i < lines.length; i++) {
+        var line = lines[i].trim();
+        if (!line || /^#/.test(line)) continue;
+        line = line.replace(/^export\s+/, '');
+        var eq = line.indexOf('=');
+        if (eq < 0) continue;
+        var key = line.slice(0, eq).trim();
+        // #B269 — strip BEFORE trimming: the shell's rule keys on the character
+        // preceding the `#`, which trimming destroys.
+        var val = stripInlineComment(line.slice(eq + 1)).trim();
+        if ( /^".*"$/.test(val) || /^'.*'$/.test(val) ) {
+            val = val.slice(1, -1);
+        }
+        map[key] = val;
+    }
+    return map;
+}
+
+/**
+ * @typedef {object} EnvFileRead
+ * @property {boolean}                   found - `true` when the file was read and parsed
+ * @property {Object<string,string>|null} map  - Parsed map when `found`, else `null`
+ * @property {string|null}               code  - `null` when `found`; else the `fs` error
+ *   code — `'ENOENT'` for a genuinely absent path, `'EACCES'` / `'EISDIR'` / … for a
+ *   path that exists but could not be read
+ */
+
+/**
+ * Read and parse a `.env`-style file, reporting WHY a read failed.
+ *
+ * `parseEnvFile` collapses every failure to `null`, which makes a file that is
+ * *missing* indistinguishable from one that exists but cannot be opened. Those
+ * two deserve opposite handling: a missing layer is a legitimate state (a project
+ * may ship a base file and add the per-scope one only on some targets), whereas a
+ * layer that exists and cannot be read is an operator error — and silently
+ * skipping it drops the bundle onto whatever lower-precedence layer remains,
+ * which for a `["<base>", "<per-scope>"]` chain means quietly running on the
+ * SHARED credential instead of the scope-specific one (#B267).
+ *
+ * Callers that must distinguish the two use this; `parseEnvFile` is kept as the
+ * map-or-`null` convenience on top of it.
+ *
+ * @memberof module:lib/secrets/env-file
+ * @function readEnvFile
+ * @param {string} filePath - Absolute path to the file
+ * @returns {EnvFileRead} Discriminated read result
+ *
+ * @example
+ * var res = readEnvFile('/run/secrets.env');
+ * if (!res.found && res.code !== 'ENOENT') {
+ *     throw new Error('secrets file exists but cannot be read: ' + res.code);
+ * }
+ *
+ * @example
+ * // A genuinely absent layer is not an error — it simply contributes nothing:
+ * readEnvFile('/run/never-created.env');   // → { found: false, map: null, code: 'ENOENT' }
+ */
+function readEnvFile(filePath) {
+    var raw;
+    try {
+        raw = fs.readFileSync(filePath, 'utf8');
+    } catch (e) {
+        // `e.code` is what discriminates: ENOENT (absent, fine) vs EACCES / EISDIR /
+        // ENOTDIR / ELOOP (present but unusable). A dangling symlink reports ENOENT,
+        // which is the correct reading — its target genuinely is not there.
+        return { found: false, map: null, code: (e && e.code) ? e.code : 'EUNKNOWN' };
+    }
+    return { found: true, map: parseEnv(raw), code: null };
+}
+
+/**
+ * Read and parse a `.env`-style file.
+ *
+ * Returns `null` — rather than throwing or returning an empty map — when the
+ * file cannot be read, so a caller can tell "unreadable" apart from "readable
+ * but empty". That distinction is load-bearing: an unreadable path is an
+ * operator error worth reporting, whereas an empty file is a legitimate state
+ * that should simply contribute no keys.
+ *
+ * ⚠️ This collapses *why* the read failed. A caller that must tell a missing
+ * file apart from an unreadable one — which is the difference between "skip this
+ * layer" and "refuse to boot" — wants {@link module:lib/secrets/env-file.readEnvFile}
+ * instead.
+ *
+ * @memberof module:lib/secrets/env-file
+ * @function parseEnvFile
+ * @param {string} filePath - Absolute path to the file
+ * @returns {Object<string,string>|null} Parsed map, or `null` if unreadable
+ *
+ * @example
+ * var map = parseEnvFile('/run/secrets.env');
+ * if (map === null) {
+ *     // unreadable — surface it; do not treat as "no secrets"
+ * }
+ */
+function parseEnvFile(filePath) {
+    var res = readEnvFile(filePath);
+    return res.found ? res.map : null;
+}
+
+module.exports = {
+    parseEnv: parseEnv,
+    parseEnvFile: parseEnvFile,
+    readEnvFile: readEnvFile
+};

package/framework/{v0.6.3 → v0.6.4}/lib/secrets/src/main.js

@@ -53,6 +53,8 @@
  */
 
 var defaultBackend = require('./backends/env');
+var fileBackend    = require('./backends/file');
+var envFile        = require('./env-file');
 
 /**
  * Regex matching an entire `${secret:KEY}` placeholder. The capture group
@@ -277,9 +279,90 @@ function getRequiredKeys(config) {
     return Object.keys(keys).sort();
 }
 
+/**
+ * Select the backend a given bundle config should resolve through.
+ *
+ * Reads `content.settings.secrets.file` — one path or an array of paths,
+ * lowest precedence first. When the key is absent the default `process.env`
+ * backend is returned **unchanged**, so a config that does not opt in behaves
+ * exactly as it did before this seam existed.
+ *
+ * Reads `content.settings` and not `settings`: `core/config.js` binds
+ * `conf[bundle][env].settings` *before* the `${…}` substitution pass and
+ * `conf[bundle][env].content` *after* it, and the substitution returns a new
+ * object rather than mutating in place — so only the `content` copy has its
+ * `${homedir}` / `${scope}` tokens resolved. Reading the other one would hand
+ * the backend a literal `'${homedir}/secrets.env'` to open.
+ *
+ * @memberof module:lib/secrets
+ * @function selectBackend
+ * @param {object} config - The merged per-bundle config (`envConf[bundle][env]`)
+ * @returns {{resolve: function(string): string}} The env backend, or an env-over-file backend
+ * @throws {Error} If a declared path is not a non-empty string, still carries an
+ *   unsubstituted `${…}` token, or contains a `${secret:…}` placeholder.
+ *
+ * @example
+ * // settings.json:
+ * //   "secrets": { "file": ["${homedir}/secrets.env",
+ * //                         "${homedir}/${scope}/secrets.env"] }
+ * var backend = secrets.selectBackend(conf);
+ * secrets.resolve(conf, backend);
+ */
+function selectBackend(config) {
+    if (config === null || typeof config !== 'object') {
+        return defaultBackend;
+    }
+    var content  = config.content;
+    var settings = (content && typeof content === 'object') ? content.settings : null;
+    var declared = (settings && typeof settings === 'object' && settings.secrets)
+        ? settings.secrets.file
+        : undefined;
+
+    if (typeof declared === 'undefined' || declared === null) {
+        return defaultBackend;
+    }
+
+    var paths = Array.isArray(declared) ? declared : [declared];
+    if (!paths.length) {
+        return defaultBackend;
+    }
+
+    for (var i = 0; i < paths.length; i++) {
+        var p = paths[i];
+        if (typeof p !== 'string' || p === '') {
+            throw new Error('`settings.secrets.file` must be a non-empty string or an array of them');
+        }
+        // A secrets file cannot itself be named by a secret — the backend that
+        // would resolve the placeholder is the one being built.
+        if (p.indexOf('${secret:') > -1) {
+            throw new Error('`settings.secrets.file` cannot contain a `${secret:…}` placeholder');
+        }
+        // Fail loudly on a token the substitution pass did not know: unknown
+        // tokens are preserved verbatim by design, so a typo would otherwise
+        // become a silent lookup for a literally-named file that never exists,
+        // and every secret would fall through to a confusing fail-closed error.
+        if (/\$\{[^}]*\}/.test(p)) {
+            throw new Error('`settings.secrets.file` contains an unresolved `${…}` token: ' + p);
+        }
+    }
+
+    return fileBackend.build(paths);
+}
+
 module.exports = {
     resolve: resolve,
     getResolvedPaths: getResolvedPaths,
     getRequiredKeys: getRequiredKeys,
-    SECRET_RE: SECRET_RE
+    selectBackend: selectBackend,
+    SECRET_RE: SECRET_RE,
+    // `.env`-style parsing, re-exported from ./env-file so that every reader
+    // of a given file agrees on what it means. See that module's header for
+    // why one implementation matters here.
+    parseEnv: envFile.parseEnv,
+    parseEnvFile: envFile.parseEnvFile,
+    // `readEnvFile` is the discriminated form — it reports WHY a read failed, so
+    // a caller can tell a genuinely absent layer (skip it) from one that exists
+    // and cannot be read (refuse). Both the runtime backend and `secrets:check`
+    // need that distinction to agree about the same file (#B267).
+    readEnvFile: envFile.readEnvFile
 };

package/framework/{v0.6.3 → v0.6.4}/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gina-framework",
-  "version": "0.6.3",
+  "version": "0.6.4",
   "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.6.3/core/gna');
+var _gna = require('./framework/v0.6.4/core/gna');
 
 // SuperController and EntitySuper — loaded from their source modules
-var SuperController = require('./framework/v0.6.3/core/controller');
-var EntitySuper     = require('./framework/v0.6.3/core/model/entity');
+var SuperController = require('./framework/v0.6.4/core/controller');
+var EntitySuper     = require('./framework/v0.6.4/core/model/entity');
 
 // uuid — from the lib registry
-var uuid = require('./framework/v0.6.3/lib/uuid');
+var uuid = require('./framework/v0.6.4/lib/uuid');
 
 module.exports = {