configre 1.2.4 → 2.0.0

package/secrets/files.js

@@ -0,0 +1,71 @@
+import fs from "node:fs";
+import crypto from "node:crypto";
+
+function stat(filename) {
+    try {
+        return fs.lstatSync(filename);
+    } catch (error) {
+        if (error.code === "ENOENT") return null;
+        throw error;
+    }
+}
+
+function readText(filename, privateFile = false) {
+    const info = stat(filename);
+    if (!info || !info.isFile()) {
+        throw new Error(`Configre secrets: expected a regular file at ${filename}`);
+    }
+    const fd = fs.openSync(filename, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW || 0));
+    try {
+        if (privateFile && process.platform !== "win32" && (fs.fstatSync(fd).mode & 0o077) !== 0) {
+            throw new Error(`Configre secrets: private identity must have owner-only permissions at ${filename}`);
+        }
+        return fs.readFileSync(fd, "utf8");
+    } finally {
+        fs.closeSync(fd);
+    }
+}
+
+function readJSON(filename) {
+    const text = readText(filename);
+    try {
+        return JSON.parse(text);
+    } catch {
+        throw new Error(`Configre secrets: invalid JSON at ${filename}`);
+    }
+}
+
+function withLock(filename, action) {
+    const lockPath = filename + ".lock";
+    let fd;
+    try {
+        fd = fs.openSync(lockPath, "wx", 0o600);
+    } catch (error) {
+        if (error.code !== "EEXIST") throw error;
+        throw new Error(`Configre secrets: another writer holds ${lockPath}; retry after it finishes, or remove the lock only if the writer has stopped`);
+    }
+    try {
+        return action();
+    } finally {
+        fs.closeSync(fd);
+        fs.unlinkSync(lockPath);
+    }
+}
+
+function writeEncrypted(filename, envelope) {
+    const temporary = `${filename}.${crypto.randomUUID()}.tmp`;
+    const fd = fs.openSync(temporary, "wx", 0o600);
+    try {
+        try {
+            fs.writeFileSync(fd, JSON.stringify(envelope, null, 2) + "\n");
+            fs.fsyncSync(fd);
+        } finally {
+            fs.closeSync(fd);
+        }
+        fs.renameSync(temporary, filename);
+    } finally {
+        if (stat(temporary)) fs.unlinkSync(temporary);
+    }
+}
+
+export { stat, readText, readJSON, withLock, writeEncrypted };

package/secrets/identity.js

@@ -0,0 +1,44 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { generatePrivateKey, parsePrivateKey, parsePublicKey } from "./crypto.js";
+import { stat, readText, withLock } from "./files.js";
+
+function loadIdentity() {
+    const directory = path.join(os.homedir(), ".config", "configre");
+    const privatePath = path.join(directory, "identity.pem");
+    const publicPath = path.join(directory, "identity.pub");
+    fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
+    const info = stat(directory);
+    if (!info.isDirectory() || (process.platform !== "win32" && (info.mode & 0o077) !== 0)) {
+        throw new Error(`Configre secrets: identity directory must be private and not a symlink at ${directory}`);
+    }
+
+    function readIdentity() {
+        const identity = parsePrivateKey(readText(privatePath, true));
+        const published = parsePublicKey(readText(publicPath));
+        if (published.fingerprint !== identity.fingerprint) {
+            throw new Error("Configre secrets: public identity does not match the private key; restore the matching identity");
+        }
+        return { ...identity, publicPath };
+    }
+
+    if (stat(privatePath) && stat(publicPath) && !stat(privatePath + ".lock")) {
+        return readIdentity();
+    }
+    return withLock(privatePath, () => {
+        if (!stat(privatePath)) {
+            if (stat(publicPath)) {
+                throw new Error("Configre secrets: private identity is missing; restore it instead of replacing it");
+            }
+            fs.writeFileSync(privatePath, generatePrivateKey(), { flag: "wx", mode: 0o600 });
+        }
+        const identity = parsePrivateKey(readText(privatePath, true));
+        if (!stat(publicPath)) {
+            fs.writeFileSync(publicPath, identity.publicKey, { flag: "wx", mode: 0o644 });
+        }
+        return readIdentity();
+    });
+}
+
+export default loadIdentity;

package/secrets/index.js

@@ -0,0 +1,172 @@
+import fs from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { isDeepStrictEqual } from "node:util";
+import { createRequire } from "node:module";
+import loadIdentity from "./identity.js";
+import registerRecipient from "./register.js";
+import { parsePublicKey, validateSecrets, encrypt, decrypt } from "./crypto.js";
+import { stat, readText, readJSON, withLock, writeEncrypted } from "./files.js";
+
+const requireSecret = createRequire(import.meta.url);
+
+function secretPaths(configPath, configFile) {
+    const directory = fs.statSync(configPath, { throwIfNoEntry: false })?.isDirectory();
+    const parent = directory ? path.resolve(configPath) : path.dirname(configFile);
+    const prefix = directory ? "" : path.basename(configFile) + ".";
+    if (/[\r\n]/.test(prefix)) {
+        throw new Error("Configre secrets: config filenames cannot contain newlines");
+    }
+    return {
+        parent, directory,
+        local: path.join(parent, path.basename(configFile, path.extname(configFile)) + ".secret.cjs"),
+        recipients: path.join(parent, prefix + "recipients"),
+        encrypted: path.join(parent, prefix + "secrets.enc.json")
+    };
+}
+
+function inGitRepository(directory) {
+    for (let current = directory; ; current = path.dirname(current)) {
+        if (stat(path.join(current, ".git"))) return true;
+        if (current === path.dirname(current)) return false;
+    }
+}
+
+function prepareIgnore(paths) {
+    const localName = path.basename(paths.local);
+    const recipientsName = path.basename(paths.recipients);
+    if (inGitRepository(paths.parent)) {
+        const result = spawnSync("git", ["-C", paths.parent, "ls-files", "-z"], {
+            encoding: "utf8",
+            env: { ...process.env, GIT_OPTIONAL_LOCKS: "0", GIT_LITERAL_PATHSPECS: "1" }
+        });
+        if (result.error || result.status !== 0) {
+            throw new Error("Configre secrets: could not check whether local secret files are tracked by Git");
+        }
+        const tracked = result.stdout.split("\0").some(name =>
+            paths.directory ? !name.includes("/") && name.endsWith(".secret.cjs") : name === localName);
+        if (tracked) {
+            throw new Error("Configre secrets: local secrets are tracked by Git; untrack them before continuing (existing Git history is not removed)");
+        }
+    }
+    const ignorePath = path.join(paths.parent, ".gitignore");
+    const existing = stat(ignorePath) ? readText(ignorePath) : "";
+    const escape = name => name.replace(/([\\*?\[\] !#])/g, "\\$1");
+    const encryptedName = escape(path.basename(paths.encrypted));
+    const rules = [
+        paths.directory ? "/*.secret.cjs" : "/" + escape(localName),
+        "!/" + escape(recipientsName) + "/",
+        "!/" + escape(recipientsName) + "/*.pub",
+        "/" + encryptedName + ".lock",
+        "/" + encryptedName + ".*.tmp"
+    ];
+    const lines = existing.split(/\r?\n/).filter(line => line && !line.startsWith("#"));
+    if (!isDeepStrictEqual(lines.slice(-rules.length), rules)) {
+        fs.appendFileSync(ignorePath, (existing && !existing.endsWith("\n") ? "\n" : "") + rules.join("\n") + "\n");
+    }
+}
+
+function loadRecipients(directory, identity) {
+    if (!stat(directory)) fs.mkdirSync(directory, { mode: 0o700 });
+    if (!stat(directory).isDirectory()) {
+        throw new Error("Configre secrets: recipients must be a directory, not a symlink");
+    }
+    const recipients = new Map([[identity.fingerprint, {
+        fingerprint: identity.fingerprint, publicKey: identity.publicKey
+    }]]);
+    for (const name of fs.readdirSync(directory).filter(name => name.endsWith(".pub")).sort()) {
+        const recipient = parsePublicKey(readText(path.join(directory, name)));
+        recipients.set(recipient.fingerprint, recipient);
+    }
+    return [...recipients.values()].sort((a, b) => a.fingerprint < b.fingerprint ? -1 : 1);
+}
+
+function localFiles(paths) {
+    return paths.directory
+        ? fs.readdirSync(paths.parent).filter(name => name.endsWith(".secret.cjs")).sort()
+        : stat(paths.local) ? [path.basename(paths.local)] : [];
+}
+
+function readSecret(filename) {
+    readText(filename);
+    try {
+        delete requireSecret.cache[requireSecret.resolve(filename)];
+        return validateSecrets(requireSecret(filename));
+    } catch {
+        throw new Error("Configre secrets: invalid secret module; export a plain object containing only JSON values");
+    }
+}
+
+function validateBundle(bundle) {
+    if (Object.keys(bundle).length !== 1 || !Object.hasOwn(bundle, "files") ||
+        !bundle.files || typeof bundle.files !== "object" || Array.isArray(bundle.files)) {
+        throw new Error("Configre secrets: invalid encrypted secrets bundle");
+    }
+    for (const [name, settings] of Object.entries(bundle.files)) {
+        if (path.basename(name) !== name || !name.endsWith(".secret.cjs")) {
+            throw new Error("Configre secrets: invalid encrypted secret filename");
+        }
+        validateSecrets(settings);
+    }
+    return bundle;
+}
+
+function selectSecrets(bundle, paths, profile) {
+    const files = bundle.files;
+    const base = files[path.basename(paths.local)] || {};
+    const selected = paths.directory
+        ? files[profile + ".dev.secret.cjs"] || files[profile + ".secret.cjs"] || {}
+        : {};
+    return [base, selected];
+}
+
+function loadSecrets(configPath, configFile, profile) {
+    const paths = secretPaths(configPath, configFile);
+    const identity = loadIdentity();
+    if (localFiles(paths).length === 0 && stat(paths.encrypted)) {
+        try {
+            return selectSecrets(validateBundle(decrypt(readJSON(paths.encrypted), identity)), paths, profile);
+        } catch (error) {
+            if (error.code !== "CONFIGRE_NOT_AUTHORIZED") throw error;
+            registerRecipient(paths, identity, profile);
+            throw new Error("Configre secrets: not authorized yet; public key is published in Git. The administrator must pull, reload Configre and publish secrets.enc.json; then pull the updated encrypted file and restart this machine");
+        }
+    }
+
+    const bundle = withLock(paths.encrypted, () => {
+        const names = localFiles(paths);
+        const hasEncrypted = !!stat(paths.encrypted);
+        const envelope = hasEncrypted ? readJSON(paths.encrypted) : null;
+        const previous = hasEncrypted ? validateBundle(decrypt(envelope, identity)) : null;
+        if (names.length === 0 && hasEncrypted) return previous;
+
+        prepareIgnore(paths);
+        const settings = { files: Object.fromEntries(names.map(name => [name, readSecret(path.join(paths.parent, name))])) };
+        const recipients = loadRecipients(paths.recipients, identity);
+        const templates = new Set([path.basename(paths.local)]);
+        if (paths.directory) {
+            for (const name of fs.readdirSync(paths.parent)) {
+                if (name.endsWith(".cjs") && !name.endsWith(".secret.cjs") && stat(path.join(paths.parent, name)).isFile()) {
+                    templates.add(name.slice(0, -4) + ".secret.cjs");
+                }
+            }
+        }
+        for (const name of templates) {
+            if (!Object.hasOwn(settings.files, name)) {
+                fs.writeFileSync(path.join(paths.parent, name), "module.exports = {};\n", { flag: "wx", mode: 0o600 });
+                settings.files[name] = {};
+            }
+        }
+        if (hasEncrypted) {
+            const previousRecipients = envelope.recipients.map(({ fingerprint, publicKey }) => ({ fingerprint, publicKey }));
+            if (isDeepStrictEqual(settings, previous) && isDeepStrictEqual(recipients, previousRecipients)) {
+                return settings;
+            }
+        }
+        writeEncrypted(paths.encrypted, encrypt(settings, recipients));
+        return settings;
+    });
+    return selectSecrets(bundle, paths, profile);
+}
+
+export default loadSecrets;

package/secrets/register.js

@@ -0,0 +1,101 @@
+import fs from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import config from "./config.js";
+import { parsePublicKey } from "./crypto.js";
+import { stat, readText, withLock } from "./files.js";
+
+function registrationError(message) {
+    return new Error(`Configre secrets: not authorized; automatic registration ${message}`);
+}
+
+function git(directory, args, operation, options = {}) {
+    const result = spawnSync("git", ["-C", directory, ...args], {
+        encoding: "utf8",
+        timeout: config.git.timeoutMs,
+        input: options.input,
+        env: {
+            ...process.env,
+            GIT_TERMINAL_PROMPT: "0",
+            GIT_OPTIONAL_LOCKS: "0",
+            GIT_LITERAL_PATHSPECS: "1",
+            ...options.env
+        }
+    });
+    if (result.error || result.status !== 0) {
+        throw registrationError(`failed while ${operation}; check Git configuration, credentials and repository state, then restart`);
+    }
+    return result.stdout;
+}
+
+function registerRecipient(paths, identity, profile) {
+    if (!/^[a-zA-Z0-9][a-zA-Z0-9._-]*$/.test(profile)) {
+        throw registrationError("requires a profile containing only letters, digits, dots, underscores or hyphens");
+    }
+    const root = git(paths.parent, ["rev-parse", "--show-toplevel"], "locating the Git repository").trim();
+    const lock = git(root, ["rev-parse", "--path-format=absolute", "--git-path", "configre-registration"], "locating the Git lock").trim();
+    return withLock(lock, () => {
+        const branch = git(root, ["symbolic-ref", "--quiet", "HEAD"], "finding the current branch (detached HEAD is unsupported)").trim();
+        const branchName = branch.slice("refs/heads/".length);
+        const remote = git(root, ["config", "--get", `branch.${branchName}.remote`], "finding the branch's upstream remote").trim();
+        const remoteBranch = git(root, ["config", "--get", `branch.${branchName}.merge`], "finding the branch's upstream ref").trim();
+        if (!remoteBranch.startsWith("refs/heads/")) {
+            throw registrationError("requires an upstream branch");
+        }
+        git(root, ["fetch", "--no-tags", "--no-recurse-submodules", "--", remote, remoteBranch], "fetching the upstream branch");
+        const remoteHead = git(root, ["rev-parse", "FETCH_HEAD"], "reading the fetched commit").trim();
+        const head = git(root, ["rev-parse", "HEAD"], "reading the local commit").trim();
+        const directory = path.join(fs.realpathSync(paths.parent), path.basename(paths.recipients));
+        const filename = path.join(directory, profile + ".pub");
+        const relative = path.relative(root, filename).split(path.sep).join("/");
+        if (relative.startsWith("../") || path.isAbsolute(relative)) {
+            throw registrationError("requires the recipients directory to be inside the repository");
+        }
+        if (stat(directory) && !stat(directory).isDirectory()) {
+            throw registrationError("requires a recipients directory that is not a symlink");
+        }
+        let publicKey = identity.publicKey;
+        if (stat(filename)) {
+            publicKey = readText(filename);
+            if (parsePublicKey(publicKey).fingerprint !== identity.fingerprint) {
+                throw registrationError("found a different key for this profile; use a distinct profile or resolve the key replacement explicitly");
+            }
+        }
+        const entry = git(root, ["ls-tree", "-z", remoteHead, "--", relative], "checking the published public key");
+        if (entry) {
+            const match = /^100644 blob ([a-f0-9]+)\t[^\0]*\0$/.exec(entry);
+            if (!match || parsePublicKey(git(root, ["cat-file", "blob", match[1]], "reading the published public key")).fingerprint !== identity.fingerprint) {
+                throw registrationError("found a different published key for this profile; use a distinct profile or resolve the key replacement explicitly");
+            }
+            if (stat(filename)) {
+                git(root, ["update-index", "--add", "--cacheinfo", "100644", match[1], relative], "reconciling the published public-key index entry");
+            }
+            return;
+        }
+        if (head !== remoteHead) {
+            throw registrationError("requires the local branch to match its upstream before publishing; synchronize the checkout without discarding local work");
+        }
+
+        const temporary = fs.mkdtempSync(path.join(path.dirname(lock), "configre-registration-"));
+        const env = { GIT_INDEX_FILE: path.join(temporary, "index") };
+        try {
+            git(root, ["read-tree", head], "preparing the isolated Git index", { env });
+            const blob = git(root, ["hash-object", "-w", "--stdin"], "storing the public key", { input: publicKey }).trim();
+            git(root, ["update-index", "--add", "--cacheinfo", "100644", blob, relative], "adding the public key to the isolated index", { env });
+            const tree = git(root, ["write-tree"], "building the registration tree", { env }).trim();
+            const commit = git(root, ["commit-tree", tree, "-p", head, "-m", `Configre: register ${profile}`], "creating the public-key commit (Git author identity must be configured)").trim();
+            fs.mkdirSync(directory, { recursive: true });
+            if (!stat(filename)) fs.writeFileSync(filename, publicKey, { flag: "wx", mode: 0o644 });
+            git(root, ["push", "--no-verify", "--no-follow-tags", "--", remote, `${commit}:${remoteBranch}`], "pushing the public-key commit");
+            if (git(root, ["symbolic-ref", "--quiet", "HEAD"], "checking the current branch").trim() !== branch) {
+                throw registrationError("published the public key, but the local branch changed concurrently; synchronize the checkout");
+            }
+            git(root, ["update-ref", branch, commit, head], "updating the local branch after publication");
+            git(root, ["update-index", "--add", "--cacheinfo", "100644", blob, relative], "updating the public-key index entry after publication");
+        } finally {
+            fs.rmSync(temporary, { recursive: true, force: true });
+        }
+    });
+}
+
+export default registerRecipient;

package/skills/configre/SKILL.md

@@ -14,6 +14,8 @@ Environment-specific configuration manager for Node.js. Merges a default config
 
 ### Step 1: Install the package
 
+Requires Node.js 22.13 or later. Configre is native ESM and supports synchronous CommonJS consumers through the same implementation.
+
 ```bash
 npm install configre --save
 ```
@@ -63,16 +65,23 @@ module.exports = {
 ### Step 5: Load the configuration
 
 ```javascript
-const cfg = require("configre")();
+import Configre from "configre";
+import { join } from "node:path";
+
+const cfg = Configre(join(import.meta.dirname, "config"));
 
 console.log(cfg.db.host); // from default
 console.log(cfg.db.user); // from host override
 ```
 
-To use a custom config directory:
+CommonJS consumers can still use `const Configre = require("configre")` and `Configre(path.join(__dirname, "config"))`, without `.default` or `await`. Configuration files remain `.cjs` in either module system.
+
+The path argument is required. Prefer an absolute path anchored to the module. Do not recommend paths derived from `process.cwd()`, such as `path.join(process.cwd(), "config")`: they can point somewhere else when the process is launched from a different directory.
+
+To use a different config directory:
 
 ```javascript
-const cfg = require("configre")(__dirname + "/settings");
+const cfg = Configre(join(import.meta.dirname, "settings"));
 ```
 
 ## Profile resolution
@@ -96,7 +105,7 @@ Using `--config=` (instead of a positional argument) avoids conflicts with other
 
 **Example 1: Basic setup**
 User says: "Add configuration management to my Node.js project"
-Actions: install configre, create `config/index.cjs` with project defaults, load with `require("configre")()`
+Actions: install configre, create `config/index.cjs` with project defaults, import Configre and load with `Configre(join(import.meta.dirname, "config"))`
 Result: merged config object ready to use
 
 **Example 2: Multi-environment**
@@ -113,4 +122,5 @@ Result: staging overrides are merged over defaults, without conflicting with oth
 
 - **Deep merge**: nested objects merge recursively via lodash `_.merge`
 - **Config files must use the `.cjs` extension** (`.js` is not accepted; works in both CommonJS and ESM projects)
+- **Required path**: always pass the config directory or file path; prefer an absolute module-relative path over a process-relative path
 - **Function vs constructor**: `Configre(path)` returns the merged config directly; `new Configre(path)` returns the instance (use `.get()` to retrieve config)

package/test/index.test.js

@@ -0,0 +1,67 @@
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import test from "node:test";
+import Configre from "../index.js";
+
+test("requires a config path", () => {
+    assert.throws(
+        () => Configre(),
+        {
+            name: "TypeError",
+            message: "Configre path must be a non-empty string"
+        }
+    );
+    assert.throws(
+        () => new Configre(""),
+        {
+            name: "TypeError",
+            message: "Configre path must be a non-empty string"
+        }
+    );
+});
+
+test("loads config from an explicit module-relative path", () => {
+    const configPath = path.join(import.meta.dirname, "..", "demo", "config");
+    const config = Configre(configPath);
+
+    assert.equal(config.db.host, "localhost");
+});
+
+for (const format of ["commonjs", "module"]) {
+    test(`package entrypoint supports ${format} consumers and shares the same function across loaders`, t => {
+        const directory = fs.mkdtempSync(path.join(os.tmpdir(), "configre-interop-"));
+        t.after(() => fs.rmSync(directory, { recursive: true, force: true }));
+        fs.mkdirSync(path.join(directory, "node_modules"));
+        fs.symlinkSync(path.join(import.meta.dirname, ".."), path.join(directory, "node_modules", "configre"), "junction");
+        const config = path.join(directory, "config");
+        fs.mkdirSync(config);
+        fs.writeFileSync(path.join(config, "index.cjs"), 'module.exports = { db: { host: "localhost", port: 123 } };');
+        fs.writeFileSync(path.join(config, "interop.cjs"), 'module.exports = { db: { port: 456 } };');
+
+        const entry = format === "commonjs" ? `
+            const assert = require('node:assert/strict');
+            const Configre = require('configre');
+            import('configre').then(module => assert.equal(module.default, Configre));
+        ` : `
+            import assert from 'node:assert/strict';
+            import { createRequire } from 'node:module';
+            import Configre from 'configre';
+            const require = createRequire(import.meta.url);
+            assert.equal(require('configre'), Configre);
+        `;
+        const filename = path.join(directory, format === "commonjs" ? "consumer.cjs" : "consumer.mjs");
+        fs.writeFileSync(filename, entry + `
+            assert.equal(typeof Configre, 'function');
+            const configPath = ${JSON.stringify(config)};
+            const expected = { db: { host: 'localhost', port: 456 } };
+            assert.deepEqual(Configre(configPath), expected);
+            assert.deepEqual(new Configre(configPath).get(), expected);
+            assert.throws(() => Configre(), /path must be a non-empty string/);
+        `);
+        const result = spawnSync(process.execPath, [filename, "--config=interop"], { encoding: "utf8" });
+        assert.equal(result.status, 0, result.stderr);
+    });
+}