@synoi/gateway-lite 0.1.0

package/dist/gap/lite-keystore.js

@@ -0,0 +1,351 @@
+"use strict";
+/**
+ * gap/lite-keystore.ts — OS credential-store wrapper for the lite operator
+ * signing key (Adversary #1 / Security F3, 2026-07-12 quality gate).
+ *
+ * PROBLEM: the operator self-sign key (lite-signing-key.ts) was a plaintext
+ * JSON file. `mode: 0o600` on the write is a NO-OP on Windows (NTFS ACLs, not
+ * POSIX mode bits, govern access there; Node's `fs` mode parameter is
+ * silently ignored on Windows), so on the platform most self-hosters
+ * actually run this on, the key was readable by ANY process running as the
+ * same OS user with no additional barrier at all.
+ *
+ * CHOICE (founder-directed, "BOTH"): wrap the key at rest with the native OS
+ * credential store where available, keep a documented, hardened file
+ * fallback where it is not.
+ *
+ * ABSTRACTION CHOICE: shell out to the OS's OWN already-installed credential
+ * CLI (PowerShell + DPAPI on Windows, `security` on macOS, `secret-tool` on
+ * Linux) rather than pulling in an npm binding (e.g. keytar, which is
+ * unmaintained and requires a native-compiled addon per platform/Node ABI).
+ * A native addon dependency would work against the whole point of
+ * @synoi/gateway-lite: `npx @synoi/gateway-lite` must install and run with nothing
+ * beyond what npm and the OS already provide. Shelling out to the OS's own
+ * tool has no compile step, no prebuilt-binary matrix to maintain, and fails
+ * CLEANLY (ENOENT / non-zero exit) when the tool is absent, which is exactly
+ * the signal isAvailable() below needs to trigger the documented fallback.
+ *
+ * PLATFORM COVERAGE (tested vs implemented-per-documented-behavior):
+ *   - Windows (DPAPI via PowerShell `System.Security.Cryptography.
+ *     ProtectedData`, CurrentUser scope): TESTED in this session (real
+ *     PowerShell process, real protect/unprotect round-trip). DPAPI ships
+ *     with every Windows install; no separate tool to be missing.
+ *   - macOS (`security` CLI, the standard Keychain command-line tool):
+ *     IMPLEMENTED per documented `security add-generic-password` /
+ *     `find-generic-password` behavior. NOT executable-tested in this
+ *     session (no macOS runner available). `security` ships with every
+ *     macOS install.
+ *   - Linux (`secret-tool`, part of libsecret-tools / gnome-keyring):
+ *     IMPLEMENTED per documented `secret-tool store` / `lookup` behavior.
+ *     NOT executable-tested in this session. NOT guaranteed present on a
+ *     minimal/headless/server Linux install (no desktop keyring daemon) --
+ *     this is the platform most likely to hit the file fallback for a
+ *     legitimate reason, not a bug.
+ *
+ * FALLBACK: if the platform's keystore is unavailable (tool missing, no
+ * desktop session, permission denied, or any other failure), lite-signing-
+ * key.ts falls back to the existing file-based store, hardened by this
+ * session's Windows ACL fix (icacls owner-only, see hardenFileAcl below),
+ * with a LOUD warning surfaced at boot (src/daemon.ts) and disclosed in
+ * packages/gateway-lite/README.md. The fallback is not silent.
+ *
+ * No em dashes. No AI attribution.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.detectKeystorePlatform = detectKeystorePlatform;
+exports._setForceUnavailableForTest = _setForceUnavailableForTest;
+exports.createLiteKeystore = createLiteKeystore;
+exports.hardenFileAcl = hardenFileAcl;
+const node_child_process_1 = require("node:child_process");
+const node_util_1 = require("node:util");
+const fs = __importStar(require("node:fs"));
+const execFileAsync = (0, node_util_1.promisify)(node_child_process_1.execFile);
+const KEYSTORE_SERVICE = 'synoi-gateway-lite-signing-key';
+function detectKeystorePlatform() {
+    if (process.platform === 'win32')
+        return 'windows-dpapi';
+    if (process.platform === 'darwin')
+        return 'macos-keychain';
+    if (process.platform === 'linux')
+        return 'linux-secret-tool';
+    return 'unsupported';
+}
+// ── Windows: DPAPI via PowerShell ───────────────────────────────────────────
+//
+// DPAPI (Data Protection API) encrypts to a blob only the SAME Windows user
+// account can decrypt (CurrentUser scope), using OS-managed key material
+// derived from the user's login credentials. Node has no built-in DPAPI
+// binding; PowerShell's full .NET access (System.Security.Cryptography.
+// ProtectedData) is the OS-native tool for this, present on every Windows
+// install with PowerShell (which ships by default since Windows 7 / Server
+// 2008 R2). The secret is passed via an environment variable to the child
+// process, not a command-line argument, so it does not appear in process
+// listings (ps / Get-Process / Task Manager command-line columns).
+//
+// Storage location: since DPAPI protects BYTES, not a keyed store, "store"
+// here just returns the protected blob (base64) for the caller to persist
+// wherever it likes (lite-signing-key.ts writes it to the same file path the
+// plaintext fallback would have used, but the file now holds ciphertext).
+// "account" is accepted for interface symmetry with the other platforms but
+// is not otherwise used by DPAPI itself.
+class WindowsDpapiKeystore {
+    platform = 'windows-dpapi';
+    filePath;
+    constructor(filePath) {
+        this.filePath = filePath;
+    }
+    async isAvailable() {
+        if (process.platform !== 'win32')
+            return false;
+        try {
+            const { stdout } = await execFileAsync('powershell', [
+                '-NoProfile', '-NonInteractive', '-Command',
+                'Add-Type -AssemblyName System.Security; "ok"',
+            ]);
+            return stdout.trim() === 'ok';
+        }
+        catch {
+            return false;
+        }
+    }
+    async store(_account, secret) {
+        const { stdout } = await execFileAsync('powershell', ['-NoProfile', '-NonInteractive', '-Command', DPAPI_PROTECT_SCRIPT], { env: { ...process.env, SYNOI_DPAPI_INPUT: secret } });
+        const protectedBase64 = stdout.trim();
+        fs.writeFileSync(this.filePath, protectedBase64, { encoding: 'utf8', mode: 0o600 });
+    }
+    async retrieve(_account) {
+        if (!fs.existsSync(this.filePath))
+            return null;
+        const protectedBase64 = fs.readFileSync(this.filePath, 'utf8').trim();
+        if (protectedBase64 === '')
+            return null;
+        try {
+            const { stdout } = await execFileAsync('powershell', ['-NoProfile', '-NonInteractive', '-Command', DPAPI_UNPROTECT_SCRIPT], { env: { ...process.env, SYNOI_DPAPI_INPUT: protectedBase64 } });
+            return stdout.trim();
+        }
+        catch {
+            return null;
+        }
+    }
+}
+const DPAPI_PROTECT_SCRIPT = [
+    'Add-Type -AssemblyName System.Security;',
+    '$bytes = [System.Text.Encoding]::UTF8.GetBytes($env:SYNOI_DPAPI_INPUT);',
+    '$protected = [System.Security.Cryptography.ProtectedData]::Protect(',
+    '  $bytes, $null, [System.Security.Cryptography.DataProtectionScope]::CurrentUser);',
+    '[Convert]::ToBase64String($protected)',
+].join(' ');
+const DPAPI_UNPROTECT_SCRIPT = [
+    'Add-Type -AssemblyName System.Security;',
+    '$bytes = [Convert]::FromBase64String($env:SYNOI_DPAPI_INPUT);',
+    '$unprotected = [System.Security.Cryptography.ProtectedData]::Unprotect(',
+    '  $bytes, $null, [System.Security.Cryptography.DataProtectionScope]::CurrentUser);',
+    '[System.Text.Encoding]::UTF8.GetString($unprotected)',
+].join(' ');
+// ── macOS: the `security` CLI (Keychain) ───────────────────────────────────
+//
+// IMPLEMENTED per documented `security` behavior; not executable-tested in
+// this session (no macOS runner available here). `-w <secret>` on the store
+// path is the standard, documented `security add-generic-password` usage.
+//
+// Security re-clear (2026-07-12): checked for a non-argv input path before
+// accepting this. `secret-tool store` (the Linux path below) documents
+// reading its secret from STDIN, so the same was investigated here.
+// `security(1)`'s `add-generic-password` does not document an equivalent:
+// `-w` takes its value as a literal argument or, if omitted entirely,
+// prompts interactively at a TTY (not usable from a non-interactive daemon
+// spawn). There is no documented `-w -` / stdin form, and no separate
+// subcommand that stores a generic password from STDIN. So this remains a
+// known, accepted characteristic of the `security` CLI itself, not a gap in
+// this code: the secret is briefly visible as a process argument during the
+// store call only (a narrow, one-time window at first run; retrieval does
+// not re-expose it). Deleting-then-adding (rather than -U/--update in
+// place) sidesteps a `security` quirk where -U silently no-ops on certain
+// macOS versions when the access-control list differs.
+class MacosKeychainKeystore {
+    platform = 'macos-keychain';
+    async isAvailable() {
+        if (process.platform !== 'darwin')
+            return false;
+        try {
+            await execFileAsync('security', ['-h']);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    async store(account, secret) {
+        // Best-effort delete of any prior entry, then add fresh. Ignore a
+        // "could not be found" failure on delete (nothing to remove yet).
+        try {
+            await execFileAsync('security', ['delete-generic-password', '-a', account, '-s', KEYSTORE_SERVICE]);
+        }
+        catch {
+            /* no prior entry; fine */
+        }
+        await execFileAsync('security', [
+            'add-generic-password', '-a', account, '-s', KEYSTORE_SERVICE, '-w', secret,
+        ]);
+    }
+    async retrieve(account) {
+        try {
+            const { stdout } = await execFileAsync('security', [
+                'find-generic-password', '-a', account, '-s', KEYSTORE_SERVICE, '-w',
+            ]);
+            const value = stdout.trim();
+            return value === '' ? null : value;
+        }
+        catch {
+            return null;
+        }
+    }
+}
+// ── Linux: `secret-tool` (libsecret) ────────────────────────────────────────
+//
+// IMPLEMENTED per documented `secret-tool` behavior; not executable-tested
+// in this session. Unlike macOS `security -w`, `secret-tool store` reads the
+// secret from STDIN, so it never appears as a process argument at all.
+// `secret-tool` requires a running secret-service provider (gnome-keyring,
+// KWallet via ksecretservice, or similar) -- routinely present on a desktop
+// Linux session, routinely ABSENT on a minimal/headless/server install. That
+// is the expected, legitimate case for isAvailable() to return false and the
+// file fallback to take over, not a defect.
+class LinuxSecretToolKeystore {
+    platform = 'linux-secret-tool';
+    async isAvailable() {
+        if (process.platform !== 'linux')
+            return false;
+        try {
+            await execFileAsync('secret-tool', ['--version']);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    async store(account, secret) {
+        await new Promise((resolve, reject) => {
+            const child = (0, node_child_process_1.spawn)('secret-tool', [
+                'store', '--label', `SynOI lite daemon operator key (${account})`,
+                'service', KEYSTORE_SERVICE, 'account', account,
+            ]);
+            let stderr = '';
+            child.stderr.on('data', (d) => { stderr += d.toString(); });
+            child.on('error', reject);
+            child.on('close', (code) => {
+                if (code === 0)
+                    resolve();
+                else
+                    reject(new Error(`secret-tool store exited ${code}: ${stderr}`));
+            });
+            child.stdin.write(secret);
+            child.stdin.end();
+        });
+    }
+    async retrieve(account) {
+        try {
+            const { stdout } = await execFileAsync('secret-tool', ['lookup', 'service', KEYSTORE_SERVICE, 'account', account]);
+            const value = stdout.trim();
+            return value === '' ? null : value;
+        }
+        catch {
+            return null;
+        }
+    }
+}
+// ── Factory ──────────────────────────────────────────────────────────────
+/** TEST ONLY: force createLiteKeystore() to return null (as if no keystore
+ *  integration exists for this platform), so the file-fallback path can be
+ *  exercised deterministically without depending on the test runner's own
+ *  platform having (or lacking) a real keystore tool. */
+let _forceUnavailableForTest = false;
+function _setForceUnavailableForTest(v) {
+    _forceUnavailableForTest = v;
+}
+/**
+ * Build the keystore for the current platform. `filePath` is only used by
+ * the Windows DPAPI implementation (it stores the protected blob at this
+ * path rather than in a separate keyed store, since DPAPI has no notion of
+ * named entries). macOS/Linux ignore it (they use the OS's own keyed store).
+ */
+function createLiteKeystore(filePath) {
+    if (_forceUnavailableForTest)
+        return null;
+    const platform = detectKeystorePlatform();
+    if (platform === 'windows-dpapi')
+        return new WindowsDpapiKeystore(filePath);
+    if (platform === 'macos-keychain')
+        return new MacosKeychainKeystore();
+    if (platform === 'linux-secret-tool')
+        return new LinuxSecretToolKeystore();
+    return null;
+}
+// ── File-fallback hardening (Security F3, part b) ──────────────────────────
+//
+// When the OS keystore is unavailable, lite-signing-key.ts falls back to the
+// plaintext file it already used. `fs.writeFileSync(..., { mode: 0o600 })`
+// is a NO-OP on Windows (NTFS ACLs govern access, not POSIX mode bits) --
+// this was the actual gap Adversary #1 flagged. `icacls` is the Windows-
+// native tool for setting a real, enforced ACL: strip inherited permissions
+// and grant Full Control to ONLY the current user (and, implicitly,
+// Administrators via the SYSTEM/built-in Administrators group icacls always
+// preserves unless :r is paired with an explicit deny -- acceptable here
+// since an Administrator already has an unconditional escalation path to
+// any user's files on Windows regardless of this ACL). On macOS/Linux,
+// POSIX mode 0600 (already set by the writeFileSync call site) IS
+// meaningful and enforced by the kernel, so no extra step is needed there.
+async function hardenFileAcl(filePath) {
+    if (process.platform !== 'win32') {
+        // POSIX mode 0600 on the writeFileSync call already does the job.
+        return { hardened: true, detail: 'POSIX file mode 0600 (kernel-enforced)' };
+    }
+    try {
+        // /inheritance:r strips inherited ACEs; /grant:r replaces the grant list
+        // for the given principal with exactly what follows (Full Control),
+        // removing any broader access the file would otherwise have inherited
+        // from its parent directory.
+        const user = process.env['USERNAME'] ? `${process.env['USERDOMAIN'] ?? '.'}\\${process.env['USERNAME']}` : undefined;
+        if (user === undefined) {
+            return { hardened: false, detail: 'could not determine current Windows username for icacls' };
+        }
+        await execFileAsync('icacls', [filePath, '/inheritance:r', '/grant:r', `${user}:F`]);
+        return { hardened: true, detail: `icacls owner-only grant to ${user}` };
+    }
+    catch (err) {
+        return { hardened: false, detail: `icacls failed: ${err instanceof Error ? err.message : String(err)}` };
+    }
+}

package/dist/gap/lite-mode.js

@@ -0,0 +1,31 @@
+"use strict";
+/**
+ * gap/lite-mode.ts — the ONE lite-mode flag (ADR_014 Section 10, the public
+ * daemon carve-out).
+ *
+ * Factored into its own leaf module (imports nothing else under gap/) so
+ * every module that needs to branch between the full gateway's
+ * managed/KMS-hybrid behavior and the lite daemon's operator-owned self-sign
+ * behavior can read/set the SAME flag without creating an import cycle.
+ * local-ingest-router.ts (receipt signing tier) and operator-enrollment.ts
+ * (enrollment-record seal tier, Security F1 fix) both depend on this; neither
+ * imports the other for this purpose.
+ *
+ * src/daemon.ts sets this once at boot. The full gateway (src/index.ts)
+ * never sets it, so every module's existing, already-paneled full-gateway
+ * behavior is byte-for-byte unchanged when this flag is false (the default).
+ *
+ * No em dashes. No AI attribution.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isLiteMode = isLiteMode;
+exports.setLiteMode = setLiteMode;
+let _liteMode = process.env['SYNOI_LITE'] === '1';
+/** Whether the current process is running the lite self-sign tier. */
+function isLiteMode() {
+    return _liteMode;
+}
+/** daemon.ts / TEST ONLY: explicitly select lite mode. */
+function setLiteMode(v) {
+    _liteMode = v;
+}