@synoi/gateway-lite 0.1.0

package/dist/gap/operator-enrollment.js

@@ -0,0 +1,466 @@
+"use strict";
+/**
+ * gap/operator-enrollment.ts - operator identity enrollment record + auth helper.
+ *
+ * ADR_015 Fix #1: closes Attack A by requiring that the operator OID be
+ * enrolled via a signed-and-sealed record before any HITL decision is accepted.
+ *
+ * No em dashes. No AI attribution.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EnrollmentIntegrityError = exports.OperatorNotEnrolledForTenantError = exports.OperatorNotEnrolledError = exports.LITE_ENROLLMENT_PAYLOAD_TYPE = exports.ENROLLMENT_PAYLOAD_TYPE = void 0;
+exports.getEnrollmentPath = getEnrollmentPath;
+exports.verifyDsseEnrollment = verifyDsseEnrollment;
+exports._testResetEnrollmentCache = _testResetEnrollmentCache;
+exports.loadEnrollmentRecord = loadEnrollmentRecord;
+exports.saveEnrollmentRecord = saveEnrollmentRecord;
+exports.enrollOperator = enrollOperator;
+exports.assertEnrolledOperatorAuth = assertEnrolledOperatorAuth;
+exports.assertEnrolledOperator = assertEnrolledOperator;
+exports._testClearEnrollment = _testClearEnrollment;
+exports._testEnrollOperatorForTest = _testEnrollOperatorForTest;
+const node_path_1 = __importDefault(require("node:path"));
+const node_os_1 = __importDefault(require("node:os"));
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_crypto_1 = require("node:crypto");
+const ml_dsa_js_1 = require("@noble/post-quantum/ml-dsa.js");
+const ed25519_1 = require("@noble/curves/ed25519");
+const verify_router_1 = require("../verify-router");
+const key_provider_1 = require("../key-provider");
+const sraid_1 = require("@synoi/sraid");
+const lite_mode_1 = require("./lite-mode");
+const lite_signing_key_1 = require("./lite-signing-key");
+exports.ENROLLMENT_PAYLOAD_TYPE = 'application/vnd.synoi.operator-enrollment+json';
+/**
+ * Security F1 (2026-07-12 quality gate, SEVERE, ship-block): the lite
+ * enrollment seal tier. The full-gateway tier above (ENROLLMENT_PAYLOAD_TYPE,
+ * verifyDsseEnrollment below) seals with the gateway's signing bundle
+ * (verify-router.ts currentBundle()), which in production is a persisted,
+ * managed key -- correct there. In lite mode that same bundle is, by design,
+ * the SYNOI_ALLOW_EPHEMERAL_KEYS fallback: a fresh Ed25519+ML-DSA-65 pair
+ * generated in-process on EVERY boot and never written to disk. Sealing the
+ * enrollment record with it meant the seal was byte-correct at write time but
+ * unverifiable forever after, because the NEXT boot's key history starts
+ * empty and gets a DIFFERENT fresh bundle -- never the one that signed the
+ * file. loadEnrollmentRecord() then returns null, the operator reads
+ * not-enrolled, and a subsequent enrollOperator() call starts
+ * enrollment_seq back at 1 (the "already enrolled" guard and the audit
+ * trail's monotonic sequence both silently reset).
+ *
+ * FIX: in lite mode, seal with the PERSISTED operator key
+ * (lite-signing-key.ts), Ed25519-only, verified against the persisted lite
+ * public key -- the SAME key that survives a restart by construction (it is
+ * generated once and read from disk on every later boot). This removes
+ * lite's enrollment-seal dependence on SYNOI_ALLOW_EPHEMERAL_KEYS /
+ * initSigningKeys() entirely: loadEnrollmentRecord() for a lite-sealed
+ * record never touches the gateway key history.
+ *
+ * Dispatch is by the record's OWN attestation.payloadType, not by the
+ * CURRENT process's lite-mode flag: a lite-sealed record verifies correctly
+ * via the lite path regardless of what mode happens to be active when it is
+ * loaded (there is no legitimate cross-tier record today, but self-describing
+ * dispatch is strictly more robust than trusting ambient state).
+ *
+ * Uses @synoi/sraid's own `pae()` (Pre-Authentication Encoding) rather than
+ * hand-rolling a second copy of the DSSE prefix construction the way
+ * verifyDsseEnrollment below does (pre-existing code, out of scope for this
+ * fix): one canonical PAE implementation for new code.
+ */
+exports.LITE_ENROLLMENT_PAYLOAD_TYPE = 'application/vnd.synoi.operator-enrollment.lite+json';
+function signLiteEnrollmentSeal(payload) {
+    const key = (0, lite_signing_key_1.loadOrCreateLiteSigningKey)();
+    const paeBytes = (0, sraid_1.pae)(exports.LITE_ENROLLMENT_PAYLOAD_TYPE, payload);
+    const sigBytes = ed25519_1.ed25519.sign(paeBytes, key.privateKey);
+    return {
+        payloadType: exports.LITE_ENROLLMENT_PAYLOAD_TYPE,
+        payload,
+        signatures: [{ alg: 'ed25519', sig: Buffer.from(sigBytes).toString('base64') }],
+    };
+}
+/**
+ * Verify a lite-tier enrollment seal against the PERSISTED operator key.
+ * Unlike verifyDsseEnrollment (which walks the gateway's in-process key
+ * history), this checks against exactly one key: whatever
+ * loadOrCreateLiteSigningKey() currently loads from disk. That call is
+ * itself idempotent and restart-stable (same file, same key, every boot),
+ * which is the whole point of this fix. Never throws; returns false on any
+ * failure (malformed signature, wrong payloadType, key-load failure).
+ */
+function verifyLiteEnrollmentSeal(attestation, payload) {
+    if (attestation.payloadType !== exports.LITE_ENROLLMENT_PAYLOAD_TYPE)
+        return false;
+    const edSig = attestation.signatures.find(s => s.alg === 'ed25519');
+    if (edSig === undefined)
+        return false;
+    try {
+        const key = (0, lite_signing_key_1.loadOrCreateLiteSigningKey)();
+        const paeBytes = (0, sraid_1.pae)(attestation.payloadType, payload);
+        return ed25519_1.ed25519.verify(Buffer.from(edSig.sig, 'base64'), paeBytes, key.publicKey);
+    }
+    catch {
+        return false;
+    }
+}
+class OperatorNotEnrolledError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'OperatorNotEnrolledError';
+        this.code = code;
+    }
+}
+exports.OperatorNotEnrolledError = OperatorNotEnrolledError;
+/**
+ * Thrown when the operator IS enrolled but NOT for the requested tenant
+ * (ADR_015 Section 10.2.A). Distinct from OperatorNotEnrolledError so the
+ * failure mode is observable at the router level.
+ */
+class OperatorNotEnrolledForTenantError extends Error {
+    code;
+    constructor(message) {
+        super(message);
+        this.name = 'OperatorNotEnrolledForTenantError';
+        this.code = 'operator_not_enrolled_for_tenant';
+    }
+}
+exports.OperatorNotEnrolledForTenantError = OperatorNotEnrolledForTenantError;
+class EnrollmentIntegrityError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'EnrollmentIntegrityError';
+    }
+}
+exports.EnrollmentIntegrityError = EnrollmentIntegrityError;
+function getEnrollmentPath() {
+    return node_path_1.default.join(process.env['SYNOI_DATA_DIR'] ?? node_path_1.default.join(node_os_1.default.homedir(), '.synoi'), 'operator-enrollment.json');
+}
+// The enrollment-seal content-core is canonicalized with the SINGLE @synoi/sraid
+// serializer (RFC 8785 JCS). The previous local `canonicalize` copy was
+// byte-identical to @synoi/sraid for the seal content-core (schema_version,
+// enrolled_operators[], enrollment_seq integer, updated_at) across all in-use
+// records; removing it leaves exactly one canonicalization path.
+/**
+ * Verify a DSSE enrollment attestation. Reconstructs PAE from the attestation
+ * and checks Ed25519 + ML-DSA-65 over those PAE bytes, against every key in history.
+ * Returns true only if both algorithms verify with the SAME bundle.
+ */
+function verifyDsseEnrollment(attestation, payload) {
+    const enc = new TextEncoder();
+    const typeBytes = enc.encode(attestation.payloadType);
+    const bodyBytes = enc.encode(payload);
+    const prefix = enc.encode(`DSSEv1 ${typeBytes.length} ${attestation.payloadType} ${bodyBytes.length} `);
+    const paeBytes = new Uint8Array(prefix.length + bodyBytes.length);
+    paeBytes.set(prefix, 0);
+    paeBytes.set(bodyBytes, prefix.length);
+    const edSig = attestation.signatures.find(s => s.alg === 'ed25519');
+    const mlSig = attestation.signatures.find(s => s.alg === 'ml-dsa-65');
+    if (!edSig || !mlSig)
+        return false;
+    const edSigBytes = Buffer.from(edSig.sig, 'base64');
+    const mlSigBytes = Buffer.from(mlSig.sig, 'base64');
+    for (const bundle of (0, key_provider_1.getKeyHistory)()) {
+        let edOk = false;
+        let mlOk = false;
+        try {
+            const keyObj = (0, node_crypto_1.createPublicKey)({ key: bundle.ed25519.publicKeyPem, format: 'pem' });
+            edOk = (0, node_crypto_1.verify)(null, Buffer.from(paeBytes), keyObj, edSigBytes);
+        }
+        catch { /* fail-closed */ }
+        try {
+            const { publicKey: mlPub } = ml_dsa_js_1.ml_dsa65.keygen(bundle.mlDsa.seed);
+            mlOk = ml_dsa_js_1.ml_dsa65.verify(mlSigBytes, paeBytes, mlPub);
+        }
+        catch { /* fail-closed */ }
+        if (edOk && mlOk)
+            return true;
+    }
+    return false;
+}
+let _enrollmentCache = null;
+/** TEST ONLY: drop the verified-enrollment cache. */
+function _testResetEnrollmentCache() {
+    _enrollmentCache = null;
+}
+/**
+ * Load the enrollment record from disk, verify the DSSE seal.
+ * Returns null on ANY failure (missing file, parse error, seal failure, schema mismatch).
+ * NEVER throws. NEVER fails-open.
+ */
+function loadEnrollmentRecord() {
+    try {
+        const p = getEnrollmentPath();
+        if (!node_fs_1.default.existsSync(p)) {
+            _enrollmentCache = null;
+            return null;
+        }
+        // [2] mtime+size cache: skip the ML-DSA seal re-verify when the file is unchanged.
+        const st = node_fs_1.default.statSync(p);
+        if (_enrollmentCache &&
+            _enrollmentCache.mtimeMs === st.mtimeMs &&
+            _enrollmentCache.size === st.size) {
+            return _enrollmentCache.record;
+        }
+        const raw = node_fs_1.default.readFileSync(p, 'utf8');
+        const record = JSON.parse(raw);
+        if (record.schema_version !== 'operator-enrollment/1') {
+            process.stderr.write('[enrollment] schema_version mismatch\n');
+            return null;
+        }
+        // Reconstruct the content core (everything except attestation) and verify.
+        const contentCore = {
+            schema_version: record.schema_version,
+            enrolled_operators: record.enrolled_operators,
+            enrollment_seq: record.enrollment_seq,
+            updated_at: record.updated_at,
+        };
+        const payload = (0, sraid_1.canonicalize)(contentCore);
+        // Dispatch by the record's OWN payloadType (self-describing), not by the
+        // current process's lite-mode flag -- see the LITE_ENROLLMENT_PAYLOAD_TYPE
+        // doc comment above (Security F1 fix).
+        const verified = record.attestation.payloadType === exports.LITE_ENROLLMENT_PAYLOAD_TYPE
+            ? verifyLiteEnrollmentSeal(record.attestation, payload)
+            : verifyDsseEnrollment(record.attestation, payload);
+        if (!verified) {
+            process.stderr.write('[enrollment] attestation verification failed\n');
+            return null;
+        }
+        // Cache only the VERIFIED record, keyed by the exact file identity.
+        _enrollmentCache = { mtimeMs: st.mtimeMs, size: st.size, record };
+        return record;
+    }
+    catch (e) {
+        process.stderr.write(`[enrollment] load failed: ${e.message}\n`);
+        return null;
+    }
+}
+/**
+ * Build, seal, and atomically write the enrollment record.
+ */
+function saveEnrollmentRecord(operators) {
+    const schema_version = 'operator-enrollment/1';
+    const enrollment_seq = (loadEnrollmentRecord()?.enrollment_seq ?? 0) + 1;
+    const updated_at = new Date().toISOString();
+    const contentCore = { schema_version, enrolled_operators: operators, enrollment_seq, updated_at };
+    const payload = (0, sraid_1.canonicalize)(contentCore);
+    // Security F1 fix: lite mode seals with the persisted operator key (which
+    // survives a restart by construction), never the gateway's ephemeral
+    // per-boot bundle. The full gateway's existing hybrid-DSSE tier is
+    // unchanged.
+    const attestation = (0, lite_mode_1.isLiteMode)()
+        ? signLiteEnrollmentSeal(payload)
+        : (0, verify_router_1.signDssePayload)(exports.ENROLLMENT_PAYLOAD_TYPE, payload);
+    const record = {
+        schema_version,
+        enrolled_operators: operators,
+        enrollment_seq,
+        updated_at,
+        attestation,
+    };
+    const p = getEnrollmentPath();
+    const tmp = p + '.tmp';
+    node_fs_1.default.writeFileSync(tmp, JSON.stringify(record, null, 2), 'utf8');
+    node_fs_1.default.renameSync(tmp, p);
+    // [2] Invalidate the verified-record cache explicitly: a fresh write normally
+    // bumps mtime/size, but a rename within the same coarse mtime tick with an equal
+    // size could otherwise read stale. Force the next load to re-verify.
+    _enrollmentCache = null;
+}
+/**
+ * Enroll a new operator, scoped to a specific tenant (ADR_015 Section 10.2.A).
+ *
+ * Signature: enrollOperator(tenant_id, pubkeyHex, deviceLabel, opts?)
+ * Default source: 'first-run-local'.
+ *
+ * Guard behavior (per Section 10.4):
+ *   - For non-demo sources ('first-run-local' | 'magic-link'): refuses if an
+ *     active non-demo entry already exists FOR THAT tenant_id.
+ *   - For 'demo-session' source: idempotent -- may (re)enroll the same demo
+ *     tenant freely without triggering the guard.
+ *
+ * The demo route must call with source 'demo-session' and the demo tenant_id only.
+ * Production-trusted enrollment must only be called over the loopback /local surface.
+ */
+function enrollOperator(tenant_id, pubkeyHex, deviceLabel, opts) {
+    const source = opts?.source ?? 'first-run-local';
+    const existing = loadEnrollmentRecord();
+    const prior = existing?.enrolled_operators ?? [];
+    if (source !== 'demo-session') {
+        // Production sources: refuse if an active non-demo entry already exists for THIS tenant.
+        const conflict = prior.find(e => e.tenant_id === tenant_id &&
+            e.status === 'active' &&
+            e.enrollment_source !== 'demo-session');
+        if (conflict) {
+            throw new Error('operator already enrolled; use re-enrollment ceremony to change');
+        }
+    }
+    // Demo-session: idempotent on the same key -- deduplicate below.
+    const pubBytes = Buffer.from(pubkeyHex, 'hex');
+    const operator_oid = 'oid-' + (0, node_crypto_1.createHash)('sha256').update(pubBytes).digest('hex');
+    const entry = {
+        operator_oid,
+        operator_pubkey: pubkeyHex,
+        tenant_id,
+        enrollment_source: source,
+        device_label: deviceLabel,
+        enrolled_at: new Date().toISOString(),
+        status: 'active',
+    };
+    // Append; deduplicate by (tenant_id, operator_oid, enrollment_source) -- last write wins.
+    const merged = [
+        ...prior.filter(e => !(e.tenant_id === tenant_id && e.operator_oid === operator_oid && e.enrollment_source === source)),
+        entry,
+    ];
+    saveEnrollmentRecord(merged);
+}
+/**
+ * assertEnrolledOperatorAuth - steps 1-3 only (OID-binding + tenant-scoped
+ * enrolled-membership + Ed25519 signature). Does NOT check a nonce (step 4).
+ *
+ * Factored from assertEnrolledOperator per ADR_016 Section 4.5 so that both
+ * GET /local/decide-challenge (steps 1-3) and POST /local/decide (steps 1-4)
+ * share the same membership+signature core with no divergent comparator.
+ *
+ * Throws EnrollmentIntegrityError, OperatorNotEnrolledError, or
+ * OperatorNotEnrolledForTenantError on any failure.
+ *
+ * @param tenant_id   The tenant the operator must be enrolled for.
+ * @param operator_oid Caller-declared OID; checked against sha256(pubkey).
+ * @param operator_pubkey_hex Raw 32-byte Ed25519 public key as 64-char lc hex.
+ * @param signature   Ed25519 sig over canonical_signed_payload, 128-char lc hex.
+ * @param canonical_signed_payload Exact canonical string the caller signed.
+ */
+function assertEnrolledOperatorAuth(tenant_id, operator_oid, operator_pubkey_hex, signature, canonical_signed_payload) {
+    // Step 1: OID-binding
+    try {
+        const pubBytes = Buffer.from(operator_pubkey_hex, 'hex');
+        const computed = 'oid-' + (0, node_crypto_1.createHash)('sha256').update(pubBytes).digest('hex');
+        if (computed !== operator_oid) {
+            throw new EnrollmentIntegrityError('oid_binding_mismatch');
+        }
+    }
+    catch (e) {
+        if (e instanceof EnrollmentIntegrityError)
+            throw e;
+        throw new EnrollmentIntegrityError('oid_binding_mismatch');
+    }
+    // Step 2: Enrolled-membership (tenant-scoped, source-gated per Section 10.2.A + 10.2.C).
+    const record = loadEnrollmentRecord();
+    if (record === null) {
+        throw new OperatorNotEnrolledError('enrollment_missing', 'no enrollment record found or record is corrupt');
+    }
+    const anyActiveEntry = record.enrolled_operators.find(e => e.operator_oid === operator_oid && e.status === 'active');
+    if (!anyActiveEntry) {
+        throw new OperatorNotEnrolledError('not_enrolled', `operator ${operator_oid} is not in the active enrolled set`);
+    }
+    const isDemoTenant = tenant_id.startsWith('tenant:demo-') && !tenant_id.startsWith('tenant:demo-mem-');
+    const tenantEntry = record.enrolled_operators.find(e => e.operator_oid === operator_oid &&
+        e.status === 'active' &&
+        e.tenant_id === tenant_id &&
+        (isDemoTenant || e.enrollment_source !== 'demo-session'));
+    if (!tenantEntry) {
+        throw new OperatorNotEnrolledForTenantError(`operator ${operator_oid} is not enrolled for tenant ${tenant_id} with a production-trusted source`);
+    }
+    // Step 3: Signature
+    try {
+        const sigBytes = Buffer.from(signature, 'hex');
+        const msgBytes = Buffer.from(canonical_signed_payload, 'utf8');
+        const pubBytes = Buffer.from(operator_pubkey_hex, 'hex');
+        const valid = ed25519_1.ed25519.verify(sigBytes, msgBytes, pubBytes);
+        if (!valid) {
+            throw new EnrollmentIntegrityError('signature_invalid');
+        }
+    }
+    catch (e) {
+        if (e instanceof EnrollmentIntegrityError)
+            throw e;
+        throw new EnrollmentIntegrityError('signature_invalid');
+    }
+}
+/**
+ * Validate that an operator is enrolled for the given tenant and their request is authentic.
+ * Throws EnrollmentIntegrityError, OperatorNotEnrolledError, or
+ * OperatorNotEnrolledForTenantError on any failure.
+ *
+ * Steps (in order, ADR_015 Sections 3 + 10.2.A):
+ *   1. OID-binding: sha256(pubkeyBytes) == operator_oid
+ *   2. Enrolled-membership (tenant-scoped): record exists + active entry for
+ *      (operator_oid, tenant_id) with enrollment_source !== 'demo-session'.
+ *      Entries lacking tenant_id are treated as not-enrolled-for-any-tenant
+ *      (fail-CLOSED migration per Section 10.3).
+ *   3. Signature: Ed25519 sig over canonical_signed_payload with operator_pubkey_hex
+ *   4. Freshness: stored_nonce === challenge_nonce
+ *
+ * The new first arg tenant_id is the tenant the action authorizes against.
+ * Steps 1/3/4 are UNCHANGED from Sections 1-9.
+ *
+ * Delegates steps 1-3 to assertEnrolledOperatorAuth (ADR_016 Section 4.5).
+ */
+function assertEnrolledOperator(tenant_id, operator_oid, operator_pubkey_hex, signature, canonical_signed_payload, challenge_nonce, stored_nonce) {
+    // Steps 1-3: delegate to the shared auth helper (ADR_016 Section 4.5).
+    assertEnrolledOperatorAuth(tenant_id, operator_oid, operator_pubkey_hex, signature, canonical_signed_payload);
+    // Step 4: Freshness
+    if (stored_nonce === undefined) {
+        throw new EnrollmentIntegrityError('nonce_missing');
+    }
+    if (stored_nonce !== challenge_nonce) {
+        throw new EnrollmentIntegrityError('stale_or_replayed');
+    }
+}
+// -- TEST-ONLY helpers ---------------------------------------------------------
+/** TEST ONLY: delete the enrollment file if it exists. */
+function _testClearEnrollment() {
+    // Hard production stop (re-panel F2, 2026-06-22): same pattern as
+    // __setSigningBundleForTest in verify-router.ts:179. NODE_ENV=production
+    // is a hard wall regardless of SYNOI_ALLOW_EPHEMERAL_KEYS.
+    if (process.env['NODE_ENV'] === 'production') {
+        throw new Error('[operator-enrollment] _testClearEnrollment is TEST-ONLY and must not be ' +
+            "called in production (NODE_ENV === 'production').");
+    }
+    if (process.env['SYNOI_ALLOW_EPHEMERAL_KEYS'] !== 'true') {
+        throw new Error('_testClearEnrollment is TEST-ONLY; set SYNOI_ALLOW_EPHEMERAL_KEYS=true');
+    }
+    const p = getEnrollmentPath();
+    if (node_fs_1.default.existsSync(p))
+        node_fs_1.default.unlinkSync(p);
+}
+/**
+ * TEST ONLY: enroll without the "already enrolled" guard.
+ * Now requires tenant_id and accepts optional source (ADR_015 Section 10.4).
+ * The NODE_ENV=production hard-wall (re-panel F2, 2026-06-22) is UNCHANGED.
+ *
+ * Callers that previously passed only pubkeyHex must be updated to supply
+ * tenant_id (and optionally source). Default source is 'first-run-local'.
+ */
+function _testEnrollOperatorForTest(pubkeyHex, tenant_id = 'tenant:test', source = 'first-run-local') {
+    // Hard production stop (re-panel F2, 2026-06-22).
+    if (process.env['NODE_ENV'] === 'production') {
+        throw new Error('[operator-enrollment] _testEnrollOperatorForTest is TEST-ONLY and must not be ' +
+            "called in production (NODE_ENV === 'production').");
+    }
+    if (process.env['SYNOI_ALLOW_EPHEMERAL_KEYS'] !== 'true') {
+        throw new Error('_testEnrollOperatorForTest is TEST-ONLY; set SYNOI_ALLOW_EPHEMERAL_KEYS=true');
+    }
+    const pubBytes = Buffer.from(pubkeyHex, 'hex');
+    const operator_oid = 'oid-' + (0, node_crypto_1.createHash)('sha256').update(pubBytes).digest('hex');
+    const entry = {
+        operator_oid,
+        operator_pubkey: pubkeyHex,
+        tenant_id,
+        enrollment_source: source,
+        device_label: 'test-device',
+        enrolled_at: new Date().toISOString(),
+        status: 'active',
+    };
+    // Append to any existing test entries (do not wipe operators enrolled earlier
+    // in the same test run). Deduplicate by (tenant_id, operator_oid, enrollment_source).
+    const existing = loadEnrollmentRecord();
+    const prior = existing?.enrolled_operators ?? [];
+    const merged = [
+        ...prior.filter(e => !(e.tenant_id === tenant_id && e.operator_oid === operator_oid && e.enrollment_source === source)),
+        entry,
+    ];
+    saveEnrollmentRecord(merged);
+}