@synoi/gateway-lite 0.1.0

package/dist/gap/lite-signing-key.js

@@ -0,0 +1,362 @@
+"use strict";
+/**
+ * gap/lite-signing-key.ts — per-instance operator-owned self-sign key.
+ *
+ * ADR_014 Section 10.1 (public lite distribution scope): the gate that trips
+ * on public self-host distribution is keys, not multi-tenancy. The full
+ * gateway's receipt-signing identity is loaded via verify-router's
+ * initSigningKeys() -> KeyProvider chain (LocalEncryptedFileKeyProvider /
+ * AwsKmsKeyProvider), a managed-custody-oriented, Ed25519+ML-DSA-65 hybrid
+ * path. The lite self-host daemon has neither managed custody nor a KMS to
+ * reach, and must not ship on a shared Foundation X TEST key (a stranger
+ * cannot run on Foundation X test keys, ADR_014 Section 10.1).
+ *
+ * This module generates a single Ed25519 keypair ONCE, on the operator's own
+ * machine, so every receipt the daemon signs after first run uses the SAME
+ * key. This is the "operator-owned" tier: the private key never leaves the
+ * operator's own machine, distinct from a shared/baked-in TEST key and
+ * distinct from the gateway's KMS-hybrid managed-custody tier.
+ *
+ * KEY-AT-REST (Adversary #1 / Security F3, 2026-07-12 quality gate, founder
+ * choice "BOTH"):
+ *   (a) OS credential store where available -- Windows DPAPI, macOS
+ *       Keychain, Linux libsecret (gap/lite-keystore.ts). Wrapping the
+ *       private key so only the same OS user/session can unwrap it, using
+ *       key material the OS itself manages, not a key SynOI's own code
+ *       chooses or stores.
+ *   (b) A hardened file fallback when the keystore is unavailable (tool
+ *       missing, headless/server install, permission denied): the SAME
+ *       plaintext-JSON shape this module always used, but now with a REAL
+ *       Windows ACL (icacls owner-only) rather than the POSIX `mode: 0o600`
+ *       that was always a silent no-op on Windows NTFS.
+ *   (c) Loud disclosure either way: daemon.ts's boot banner and
+ *       packages/gateway-lite/README.md both state plainly that ANY process
+ *       running as the operator's OS account can sign as the operator, that
+ *       this key has no managed custody and no recovery, and (on the file
+ *       fallback path specifically) exactly how it is protected per-OS.
+ *
+ * BACKWARD COMPATIBILITY: an existing lite-signing-key.json written by a
+ * pre-fix daemon (schema_version 'lite-signing-key/1', plaintext
+ * private_key_hex directly in the file) is read AS-IS, unchanged -- an
+ * operator upgrading must not silently lose their operator identity (every
+ * receipt they ever signed, and the enrollment record sealed under that
+ * key, would become unverifiable under a new key). Only a FRESH first-run
+ * key generation uses the new schema_version 'lite-signing-key/2' shape and
+ * attempts the OS keystore.
+ *
+ * Uses @synoi/gap's own Ed25519 keygen (generateReceiptKeyPair) -- no second
+ * key-generation primitive in this codebase.
+ *
+ * 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.getLiteSigningKeyPath = getLiteSigningKeyPath;
+exports._resetLiteSigningKeyCache = _resetLiteSigningKeyCache;
+exports.loadOrCreateLiteSigningKeyAsync = loadOrCreateLiteSigningKeyAsync;
+exports.loadOrCreateLiteSigningKey = loadOrCreateLiteSigningKey;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const os = __importStar(require("node:os"));
+const gap_1 = require("@synoi/gap");
+const lite_keystore_1 = require("./lite-keystore");
+function getLiteSigningKeyPath() {
+    return path.join(process.env['SYNOI_DATA_DIR'] ?? path.join(os.homedir(), '.synoi'), 'lite-signing-key.json');
+}
+/** Where the Windows DPAPI-protected private-key blob lives, when that
+ *  backend is used. A separate file from getLiteSigningKeyPath() so the
+ *  metadata file (schema_version 'lite-signing-key/2') never itself carries
+ *  private key material for the keystore-backed backends. */
+function getDpapiBlobPath() {
+    return path.join(process.env['SYNOI_DATA_DIR'] ?? path.join(os.homedir(), '.synoi'), 'lite-signing-key.dpapi');
+}
+const KEYSTORE_ACCOUNT = 'lite-operator';
+let _cached = null;
+let _cachedResult = null;
+/** TEST ONLY: drop the in-process cache so a test pointed at a fresh
+ *  SYNOI_DATA_DIR re-reads (or re-generates) from that directory. */
+function _resetLiteSigningKeyCache() {
+    _cached = null;
+    _cachedResult = null;
+}
+function hexToBytes32(hex) {
+    const buf = Buffer.from(hex, 'hex');
+    if (buf.length !== 32)
+        throw new Error(`expected 32 bytes, got ${buf.length}`);
+    return new Uint8Array(buf);
+}
+/**
+ * Async, keystore-aware loader. Call this ONCE at daemon boot (src/
+ * daemon.ts), before any request can arrive, and before the synchronous
+ * loadOrCreateLiteSigningKey() below is used by the (synchronous) receipt-
+ * signing / enrollment-seal call paths -- it populates the same in-process
+ * cache those synchronous paths read from.
+ *
+ * On an EXISTING v1 (pre-fix) file: loaded as-is, unchanged, backend
+ * reported as 'file-fallback' (it always was; this call does not migrate it
+ * -- migrating would mean re-writing a file whose whole point is to never
+ * silently change under the operator).
+ *
+ * On an EXISTING v2 file: dispatches by its own `backend` field.
+ *
+ * On NO file (first run): tries the OS keystore; on any failure (including
+ * "no keystore for this platform") falls back to a hardened plaintext file
+ * and returns a non-empty fallbackWarning.
+ */
+async function loadOrCreateLiteSigningKeyAsync() {
+    if (_cachedResult !== null)
+        return _cachedResult;
+    const metaPath = getLiteSigningKeyPath();
+    if (fs.existsSync(metaPath)) {
+        const rec = parsePersistedFile(metaPath);
+        const result = await loadFromExisting(rec);
+        _cached = result.keyPair;
+        _cachedResult = result;
+        return result;
+    }
+    // First run.
+    const fresh = (0, gap_1.generateReceiptKeyPair)();
+    const keyId = fresh.keyId ?? ('key:' + Buffer.from(fresh.publicKey).toString('hex').slice(0, 16));
+    const publicKeyHex = Buffer.from(fresh.publicKey).toString('hex');
+    const privateKeyHex = Buffer.from(fresh.privateKey).toString('hex');
+    fs.mkdirSync(path.dirname(metaPath), { recursive: true });
+    const keystore = (0, lite_keystore_1.createLiteKeystore)(getDpapiBlobPath());
+    let usedKeystore = false;
+    let fallbackWarning = '';
+    if (keystore !== null) {
+        try {
+            const available = await keystore.isAvailable();
+            if (available) {
+                await keystore.store(KEYSTORE_ACCOUNT, privateKeyHex);
+                usedKeystore = true;
+            }
+            else {
+                fallbackWarning = `OS keystore (${keystore.platform}) not available on this machine; using the hardened file fallback.`;
+            }
+        }
+        catch (err) {
+            fallbackWarning = `OS keystore (${keystore.platform}) store failed (${err instanceof Error ? err.message : String(err)}); using the hardened file fallback.`;
+        }
+    }
+    else {
+        fallbackWarning = `No OS keystore integration for platform "${(0, lite_keystore_1.detectKeystorePlatform)()}"; using the hardened file fallback.`;
+    }
+    if (usedKeystore) {
+        const record = {
+            schema_version: 'lite-signing-key/2',
+            backend: 'os-keystore',
+            keystore_platform: (0, lite_keystore_1.detectKeystorePlatform)(),
+            public_key_hex: publicKeyHex,
+            key_id: keyId,
+            created_at: new Date().toISOString(),
+        };
+        writeMetaFile(metaPath, record);
+    }
+    else {
+        const record = {
+            schema_version: 'lite-signing-key/2',
+            backend: 'file-fallback',
+            public_key_hex: publicKeyHex,
+            key_id: keyId,
+            created_at: new Date().toISOString(),
+            private_key_hex: privateKeyHex,
+        };
+        // Security re-clear (2026-07-12): the ACL used to be hardened AFTER the
+        // plaintext-bearing file was already renamed into place at metaPath, so
+        // for the duration of the icacls process spawn (non-trivial: an async
+        // child-process round-trip, not a syscall) the private key sat on disk
+        // under its FINAL, discoverable name with whatever ACL it inherited from
+        // the parent directory -- POSIX mode 0600 on the writeFileSync call is a
+        // no-op on NTFS, so on Windows that inherited ACL could be broader than
+        // owner-only. Fix: write to the temp path, harden ITS ACL, THEN rename
+        // into place, so the file never appears at metaPath without the
+        // restrictive ACL already applied. On non-Windows this is a cheap no-op
+        // check (POSIX mode 0600 already did the job at write time); on Windows
+        // it closes the window entirely.
+        const tmp = writeMetaFileTmp(metaPath, record);
+        const acl = await (0, lite_keystore_1.hardenFileAcl)(tmp);
+        if (!acl.hardened) {
+            fallbackWarning += ` ADDITIONALLY: file ACL hardening failed (${acl.detail}) -- the key file may be readable by more than the operator's own account.`;
+        }
+        fs.renameSync(tmp, metaPath);
+    }
+    const keyPair = { privateKey: fresh.privateKey, publicKey: fresh.publicKey, keyId };
+    const result = {
+        keyPair,
+        backend: usedKeystore ? 'os-keystore' : 'file-fallback',
+        keystorePlatform: (0, lite_keystore_1.detectKeystorePlatform)(),
+        fallbackWarning,
+    };
+    _cached = keyPair;
+    _cachedResult = result;
+    return result;
+}
+async function loadFromExisting(rec) {
+    if (rec.schema_version === 'lite-signing-key/1') {
+        // Pre-fix file: read as-is, never migrated.
+        const privateKey = hexToBytes32(rec.private_key_hex);
+        const publicKey = hexToBytes32(rec.public_key_hex);
+        return {
+            keyPair: { privateKey, publicKey, keyId: rec.key_id },
+            backend: 'file-fallback',
+            fallbackWarning: '',
+        };
+    }
+    // v2.
+    if (rec.backend === 'file-fallback') {
+        if (rec.private_key_hex === undefined) {
+            throw new Error(`[lite-signing-key] v2 file-fallback record missing private_key_hex`);
+        }
+        const privateKey = hexToBytes32(rec.private_key_hex);
+        const publicKey = hexToBytes32(rec.public_key_hex);
+        return {
+            keyPair: { privateKey, publicKey, keyId: rec.key_id },
+            backend: 'file-fallback',
+            fallbackWarning: '',
+        };
+    }
+    // backend === 'os-keystore': retrieve the private key from the OS store.
+    const keystore = (0, lite_keystore_1.createLiteKeystore)(getDpapiBlobPath());
+    if (keystore === null) {
+        throw new Error(`[lite-signing-key] record says backend=os-keystore (platform=${String(rec.keystore_platform)}) but ` +
+            `this process's platform (${(0, lite_keystore_1.detectKeystorePlatform)()}) has no keystore integration. ` +
+            'The operator key cannot be recovered on this machine/platform.');
+    }
+    const privateKeyHex = await keystore.retrieve(KEYSTORE_ACCOUNT);
+    if (privateKeyHex === null) {
+        throw new Error(`[lite-signing-key] record says backend=os-keystore but the key could not be retrieved from ` +
+            `the ${keystore.platform} keystore. It may have been removed, or this process may be running as ` +
+            'a different OS user than the one that created it.');
+    }
+    const privateKey = hexToBytes32(privateKeyHex);
+    const publicKey = hexToBytes32(rec.public_key_hex);
+    return {
+        keyPair: { privateKey, publicKey, keyId: rec.key_id },
+        backend: 'os-keystore',
+        keystorePlatform: rec.keystore_platform,
+        fallbackWarning: '',
+    };
+}
+function parsePersistedFile(metaPath) {
+    let rec;
+    try {
+        rec = JSON.parse(fs.readFileSync(metaPath, 'utf8'));
+    }
+    catch (err) {
+        throw new Error(`[lite-signing-key] failed to parse ${metaPath}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    if (rec.schema_version !== 'lite-signing-key/1' && rec.schema_version !== 'lite-signing-key/2') {
+        throw new Error(`[lite-signing-key] ${metaPath}: unexpected schema_version "${String(rec.schema_version)}"`);
+    }
+    return rec;
+}
+/** Write `record` to metaPath's temp path and rename it into place in one
+ *  step, for callers with nothing to do between write and commit (the
+ *  os-keystore branch: no private key in the file, so there is no ACL
+ *  window to close). Callers who DO need to act between write and commit
+ *  (the file-fallback branch, which hardens the ACL first) use
+ *  writeMetaFileTmp + fs.renameSync directly instead. */
+function writeMetaFile(metaPath, record) {
+    const tmp = writeMetaFileTmp(metaPath, record);
+    fs.renameSync(tmp, metaPath);
+}
+/** Write `record` to metaPath's temp path ONLY; does not rename. Returns the
+ *  temp path so the caller can act on it (e.g. harden its ACL) before
+ *  committing it into place with fs.renameSync. */
+function writeMetaFileTmp(metaPath, record) {
+    const tmp = metaPath + '.tmp';
+    fs.writeFileSync(tmp, JSON.stringify(record, null, 2), { encoding: 'utf8', mode: 0o600 });
+    return tmp;
+}
+/**
+ * SYNCHRONOUS loader for the many call sites inside a request handler
+ * (receipt signing, enrollment sealing) that cannot await a keystore CLI
+ * round-trip mid-request. Returns the in-process cache if
+ * loadOrCreateLiteSigningKeyAsync() already ran (the normal daemon boot
+ * order: async loader first, then the server starts accepting requests).
+ *
+ * If called before the async loader has ever run (e.g. a test that only
+ * exercises this synchronous path directly, or a hypothetical future
+ * caller that skips the boot sequence), falls back to the ORIGINAL
+ * synchronous, file-only behavior: read an existing v1 OR v2 file-fallback
+ * record directly (no keystore attempt, since that would require an
+ * async call), or generate-and-persist a fresh v1-shaped plaintext file on
+ * first run. This preserves every existing synchronous test's behavior
+ * unchanged. A v2 os-keystore record encountered here (impossible in
+ * practice without having gone through the async loader first, since that
+ * is the only path that ever WRITES an os-keystore record) throws rather
+ * than silently failing to produce a key.
+ */
+function loadOrCreateLiteSigningKey() {
+    if (_cached !== null)
+        return _cached;
+    const p = getLiteSigningKeyPath();
+    if (fs.existsSync(p)) {
+        const rec = parsePersistedFile(p);
+        if (rec.schema_version === 'lite-signing-key/1') {
+            const privateKey = hexToBytes32(rec.private_key_hex);
+            const publicKey = hexToBytes32(rec.public_key_hex);
+            _cached = { privateKey, publicKey, keyId: rec.key_id };
+            return _cached;
+        }
+        if (rec.backend === 'file-fallback' && rec.private_key_hex !== undefined) {
+            const privateKey = hexToBytes32(rec.private_key_hex);
+            const publicKey = hexToBytes32(rec.public_key_hex);
+            _cached = { privateKey, publicKey, keyId: rec.key_id };
+            return _cached;
+        }
+        throw new Error('[lite-signing-key] existing record is backend=os-keystore, which requires the async loader ' +
+            '(loadOrCreateLiteSigningKeyAsync, called once at daemon boot) to retrieve the private key. ' +
+            'The synchronous loadOrCreateLiteSigningKey() cannot do this mid-request.');
+    }
+    // First run via the SYNCHRONOUS path only: no keystore attempt (would
+    // require awaiting a CLI round-trip). Matches the original v1 behavior
+    // exactly, for callers/tests that never invoke the async loader.
+    const fresh = (0, gap_1.generateReceiptKeyPair)();
+    const keyId = fresh.keyId ?? ('key:' + Buffer.from(fresh.publicKey).toString('hex').slice(0, 16));
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    const record = {
+        schema_version: 'lite-signing-key/1',
+        private_key_hex: Buffer.from(fresh.privateKey).toString('hex'),
+        public_key_hex: Buffer.from(fresh.publicKey).toString('hex'),
+        key_id: keyId,
+        created_at: new Date().toISOString(),
+    };
+    const tmp = p + '.tmp';
+    fs.writeFileSync(tmp, JSON.stringify(record, null, 2), { encoding: 'utf8', mode: 0o600 });
+    fs.renameSync(tmp, p);
+    _cached = { privateKey: fresh.privateKey, publicKey: fresh.publicKey, keyId };
+    return _cached;
+}