@synoi/gateway-lite 0.1.0

package/dist/gap/types.js

@@ -0,0 +1,15 @@
+"use strict";
+/**
+ * gap/types.ts — TypeScript types for the SynOI Governed Action Protocol.
+ *
+ * Mirrors the shapes in synoi-brain/libraries/v1/GAP_SPEC.md §2-§8. This is
+ * the canonical TS surface for GAP within synoi-gateway. The published
+ * @synoi/gap-types npm package will export a subset.
+ *
+ * Object types use the prefix `gap:` per spec §2.1 (signed type-prefix migrated per ADR_007)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isGapFailure = isGapFailure;
+function isGapFailure(r) {
+    return typeof r === 'object' && r !== null && 'reason' in r;
+}

package/dist/key-provider.js

@@ -0,0 +1,275 @@
+"use strict";
+/**
+ * key-provider.ts
+ *
+ * KeyProvider abstraction for persistent signing keys used in Decision Receipt
+ * signing (Ed25519 + ML-DSA-65 hybrid). Replaces the ephemeral-key pattern
+ * that was previously used on the live signing path.
+ *
+ * Design rules:
+ *  1. FAIL CLOSED in production: if NODE_ENV=production and no provider is
+ *     configured, startup throws — never fall through to ephemeral generation.
+ *  2. Key history: every loaded key is appended to an in-memory history ring
+ *     so that receipts signed with a prior key can still be verified after
+ *     rotation (without ever re-signing old receipts).
+ *  3. Providers are pluggable via the KeyProvider interface. Two implementations
+ *     exist:
+ *       a. LocalEncryptedFileKeyProvider — for self-hosted / dev-prod scenarios.
+ *          Reads PEM + seed from files that the operator places on disk. Simple,
+ *          auditable, no cloud dependency. Defined IN THIS FILE.
+ *       b. AwsKmsKeyProvider — a complete, working AWS Secrets Manager client
+ *          (not a stub). Defined in key-provider-kms.ts, a SEPARATE file,
+ *          reached from resolveKeyProvider() below ONLY via a runtime
+ *          require() (Auditor B1, 2026-07-12): this file is part of the free
+ *          @synoi/gateway-lite package's static reachable graph, and a static
+ *          import of AwsKmsKeyProvider here would compile a literal require
+ *          string naming the AWS Secrets Manager SDK package into this
+ *          file's own output, shipping cloud-SDK bytes inside a package
+ *          whose README claims zero cloud code. See key-provider-kms.ts's
+ *          header for the full rationale and the enforcing tests. (The exact
+ *          package name is deliberately not spelled out here, in this file:
+ *          it is the one string test/daemon-package-dep-graph.test.ts's
+ *          byte-level content scan forbids anywhere in the packed tarball,
+ *          comments included, and this file ships in that tarball.)
+ *
+ * AWS KMS/Secrets Manager is the locked decision for production key custody
+ * (AWS-native stack). Selection today is an env-var opt-in
+ * (SYNOI_KEY_PROVIDER=kms), not a license-tier decision; license-gating KMS
+ * selection is separate, PAPER, net-new work, not part of this file.
+ *
+ * NOTE: this file does NOT touch the canonicalizer (canonicalPayload in
+ * verify-router.ts) — that is a separate task.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LocalEncryptedFileKeyProvider = void 0;
+exports.appendKeyHistory = appendKeyHistory;
+exports.getKeyHistory = getKeyHistory;
+exports.findKeyById = findKeyById;
+exports._testClearKeyHistory = _testClearKeyHistory;
+exports.auditKeyLoad = auditKeyLoad;
+exports.getPublicKeyBase64 = getPublicKeyBase64;
+exports.resolveKeyProvider = resolveKeyProvider;
+const crypto_1 = require("crypto");
+const fs_1 = require("fs");
+const path_1 = require("path");
+// ── Key history ───────────────────────────────────────────────────────────────
+//
+// Historical receipts must remain verifiable after key rotation. Instead of
+// re-signing old receipts (which would invalidate the audit trail), the gateway
+// keeps an in-memory append-only ring of every KeyBundle that was loaded during
+// this process lifetime. Verification code iterates the history until it finds
+// a key-id match.
+//
+// The ring is bounded at MAX_HISTORY_SIZE entries to prevent unbounded memory
+// growth if many keys are rotated in a single process lifetime.
+const MAX_HISTORY_SIZE = 32;
+const _keyHistory = [];
+/** Append a bundle to the key history. No-op if the key-id is already present. */
+function appendKeyHistory(bundle) {
+    if (_keyHistory.some(b => b.keyId === bundle.keyId))
+        return;
+    if (_keyHistory.length >= MAX_HISTORY_SIZE) {
+        // Drop the oldest entry (index 0) to make room.
+        _keyHistory.shift();
+    }
+    _keyHistory.push(bundle);
+}
+/**
+ * Return all key bundles that have been loaded in this process lifetime,
+ * newest first. Used by verification to try the current key, then fall back
+ * through historical keys when a stored receipt carries an older key-id.
+ */
+function getKeyHistory() {
+    return [..._keyHistory].reverse();
+}
+/** Look up a bundle by key-id in the history. Returns undefined if not found. */
+function findKeyById(keyId) {
+    return _keyHistory.find(b => b.keyId === keyId);
+}
+/**
+ * TEST ONLY: empty the in-memory key history. Used to simulate a process
+ * restart (a fresh boot starts with an empty history, populated only by
+ * whatever initSigningKeys() loads THIS time) without actually spawning a
+ * new process. Hard-gated the same way __setSigningBundleForTest is
+ * (verify-router.ts): throws in production regardless of any other flag.
+ */
+function _testClearKeyHistory() {
+    if (process.env['NODE_ENV'] === 'production') {
+        throw new Error('[key-provider] _testClearKeyHistory is TEST-ONLY and must not be ' +
+            "called in production (NODE_ENV === 'production').");
+    }
+    _keyHistory.length = 0;
+}
+// ── LocalEncryptedFileKeyProvider ─────────────────────────────────────────────
+//
+// Reads key material from files on disk. Intended for:
+//   - Self-hosted production deployments (operator owns the files)
+//   - Developer workstations with a "test-persistent" key
+//   - CI pipelines (ephemeral but process-stable keys in temp files)
+//
+// Required env vars / files:
+//   SYNOI_ED25519_PRIVATE_KEY_FILE  — path to PKCS#8 PEM file
+//   SYNOI_ED25519_PUBLIC_KEY_FILE   — path to SPKI PEM file
+//   SYNOI_MLDSA_SEED_FILE           — path to file containing 64 hex chars (32 bytes)
+//   SYNOI_SIGNING_KEY_ID            — key identifier string (e.g. "synoi-v2-2026-06")
+//
+// Alternatively, the PEM material may be supplied directly via env vars:
+//   SYNOI_SIGNING_KEY_PRIVATE       — PKCS#8 PEM (existing variable, backward-compat)
+//   SYNOI_SIGNING_KEY_PUBLIC        — SPKI PEM (existing variable, backward-compat)
+//   SYNOI_MLDSA_SEED                — 64 hex chars (existing variable, backward-compat)
+//
+// If all three env vars are set (or all three files exist), the provider loads
+// successfully. Otherwise it throws a descriptive error.
+class LocalEncryptedFileKeyProvider {
+    async loadCurrentKey() {
+        const keyId = process.env['SYNOI_SIGNING_KEY_ID'] ?? 'synoi-v1';
+        // Ed25519 — try inline env first (backward compat), then file.
+        let privateKeyPem;
+        let publicKeyPem;
+        const privInline = process.env['SYNOI_SIGNING_KEY_PRIVATE'];
+        const pubInline = process.env['SYNOI_SIGNING_KEY_PUBLIC'];
+        const privFile = process.env['SYNOI_ED25519_PRIVATE_KEY_FILE'];
+        const pubFile = process.env['SYNOI_ED25519_PUBLIC_KEY_FILE'];
+        if (privInline && pubInline) {
+            privateKeyPem = privInline;
+            publicKeyPem = pubInline;
+        }
+        else if (privFile && pubFile) {
+            if (!(0, fs_1.existsSync)(privFile))
+                throw new Error(`[key-provider] Ed25519 private key file not found: ${privFile}`);
+            if (!(0, fs_1.existsSync)(pubFile))
+                throw new Error(`[key-provider] Ed25519 public key file not found: ${pubFile}`);
+            privateKeyPem = (0, fs_1.readFileSync)(privFile, 'utf8');
+            publicKeyPem = (0, fs_1.readFileSync)(pubFile, 'utf8');
+        }
+        else {
+            throw new Error('[key-provider] Ed25519 key not configured. ' +
+                'Set SYNOI_SIGNING_KEY_PRIVATE + SYNOI_SIGNING_KEY_PUBLIC (PEM) ' +
+                'or SYNOI_ED25519_PRIVATE_KEY_FILE + SYNOI_ED25519_PUBLIC_KEY_FILE.');
+        }
+        // Validate the PEM material loads correctly (catches file corruption early).
+        try {
+            (0, crypto_1.createPrivateKey)({ key: privateKeyPem, format: 'pem' });
+            (0, crypto_1.createPublicKey)({ key: publicKeyPem, format: 'pem' });
+        }
+        catch (err) {
+            throw new Error(`[key-provider] Ed25519 PEM validation failed: ${err.message}`);
+        }
+        // ML-DSA seed — try inline env first, then file.
+        let seed;
+        const seedInline = process.env['SYNOI_MLDSA_SEED'];
+        const seedFile = process.env['SYNOI_MLDSA_SEED_FILE'];
+        if (seedInline) {
+            const buf = Buffer.from(seedInline, 'hex');
+            if (buf.length !== 32)
+                throw new Error(`[key-provider] SYNOI_MLDSA_SEED must be 64 hex chars (32 bytes), got ${buf.length * 2}`);
+            seed = new Uint8Array(buf);
+        }
+        else if (seedFile) {
+            if (!(0, fs_1.existsSync)(seedFile))
+                throw new Error(`[key-provider] ML-DSA seed file not found: ${seedFile}`);
+            const raw = (0, fs_1.readFileSync)(seedFile, 'utf8').trim();
+            const buf = Buffer.from(raw, 'hex');
+            if (buf.length !== 32)
+                throw new Error(`[key-provider] ML-DSA seed file must contain 64 hex chars, got ${buf.length * 2}`);
+            seed = new Uint8Array(buf);
+        }
+        else {
+            throw new Error('[key-provider] ML-DSA seed not configured. ' +
+                'Set SYNOI_MLDSA_SEED (64 hex chars) or SYNOI_MLDSA_SEED_FILE.');
+        }
+        const bundle = {
+            keyId,
+            ed25519: { privateKeyPem, publicKeyPem },
+            mlDsa: { seed },
+            valid_from_ms: Date.now(),
+        };
+        appendKeyHistory(bundle);
+        return bundle;
+    }
+}
+exports.LocalEncryptedFileKeyProvider = LocalEncryptedFileKeyProvider;
+// ── AwsKmsKeyProvider ───────────────────────────────────────────────────────
+//
+// Moved to key-provider-kms.ts (Auditor B1, 2026-07-12) so this file's
+// compiled output never carries a require string naming the AWS Secrets
+// Manager SDK package. See key-provider-kms.ts for the full class and
+// rationale, and the dynamic require() in resolveKeyProvider() below for
+// how it is reached.
+// ── Key audit log ─────────────────────────────────────────────────────────────
+//
+// Optional: when SYNOI_KEY_AUDIT_LOG is set to a file path, each key-load
+// event is appended (key-id + ISO timestamp, no key material). Supports
+// compliance evidence that the same persistent key was reloaded after restart.
+function auditKeyLoad(keyId) {
+    const logPath = process.env['SYNOI_KEY_AUDIT_LOG'];
+    if (!logPath)
+        return;
+    try {
+        const dir = (0, path_1.join)(logPath, '..');
+        (0, fs_1.mkdirSync)(dir, { recursive: true });
+        (0, fs_1.appendFileSync)(logPath, JSON.stringify({ event: 'key_loaded', key_id: keyId, ts: new Date().toISOString() }) + '\n', 'utf8');
+    }
+    catch {
+        // Audit log failure is non-fatal; the key is still loaded.
+        console.warn(`[key-provider] Failed to write audit log to ${logPath}`);
+    }
+}
+// ── Public key extraction helper ──────────────────────────────────────────────
+/**
+ * Extract the raw 32-byte Ed25519 public key from a KeyBundle and return it
+ * as standard base64. Used by the GET /v1/gap/keys endpoints.
+ */
+function getPublicKeyBase64(bundle) {
+    const keyObj = (0, crypto_1.createPublicKey)({ key: bundle.ed25519.publicKeyPem, format: 'pem' });
+    const der = keyObj.export({ format: 'der', type: 'spki' });
+    return der.subarray(der.length - 32).toString('base64');
+}
+// ── Provider factory ──────────────────────────────────────────────────────────
+//
+// Resolves which KeyProvider to use based on environment configuration.
+// Called once at startup by verify-router.ts.
+//
+// Selection logic:
+//   1. SYNOI_KEY_PROVIDER=kms        -> AwsKmsKeyProvider (AWS Secrets Manager)
+//   2. SYNOI_KEY_PROVIDER=file       -> LocalEncryptedFileKeyProvider (dev/self-hosted)
+//   3. (unset in production)         -> throws: production requires explicit KMS selection
+//   4. (unset in non-production)     -> defaults to 'file'
+//
+// Production enforcement: NODE_ENV=production requires SYNOI_KEY_PROVIDER=kms.
+// The Ed25519 private key must not live in an environment variable or a file
+// accessible to the process in production — it must be in AWS Secrets Manager.
+function resolveKeyProvider() {
+    const isProduction = process.env['NODE_ENV'] === 'production';
+    const providerName = process.env['SYNOI_KEY_PROVIDER'] ?? (isProduction ? '' : 'file');
+    if (isProduction && providerName !== 'kms') {
+        throw new Error('[key-provider] Production requires SYNOI_KEY_PROVIDER=kms. ' +
+            'The Ed25519 private key must be stored in AWS Secrets Manager, not in environment variables or on disk. ' +
+            'Set SYNOI_KMS_ED25519_SECRET_ARN, SYNOI_KMS_MLDSA_SECRET_ARN, SYNOI_SIGNING_KEY_ID, and AWS_REGION.');
+    }
+    switch (providerName) {
+        case 'kms': {
+            // Dynamic require (Auditor B1, 2026-07-12), mirroring the existing
+            // precedent at verify-router.ts's tryVerifyAgpReceipt (dynamic require
+            // of gap/receipt-sign / gap/state/absence-verify): a STATIC import of
+            // AwsKmsKeyProvider here would pull key-provider-kms.ts, and through
+            // it the AWS Secrets Manager SDK require string, into this
+            // file's own compiled output -- and this file IS in the free
+            // @synoi/gateway-lite package's reachable graph. A minimal LOCAL type
+            // (not `typeof import('./key-provider-kms')`) is used for the same
+            // reason a whole-module type reference was avoided at verify-router.ts
+            // in the earlier lite-daemon-carveout work: `typeof import(...)`
+            // still pulls the target module into the TypeScript program's type
+            // graph even though the runtime require() is lazy, defeating the
+            // point. Enforced by test/daemon-dep-graph.test.ts (source-level:
+            // key-provider-kms.ts must be absent from the reachable set) and
+            // test/daemon-package-dep-graph.test.ts (byte-level content scan of
+            // the actual packed tarball).
+            const { AwsKmsKeyProvider } = require('./key-provider-kms');
+            return new AwsKmsKeyProvider();
+        }
+        case 'file': return new LocalEncryptedFileKeyProvider();
+        default:
+            throw new Error(`[key-provider] Unknown SYNOI_KEY_PROVIDER value: "${providerName}". Supported: "file", "kms".`);
+    }
+}

package/dist/keys.js

@@ -0,0 +1,250 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.keyStore = exports.KeyStore = exports.PLAN_RPM = exports.PLAN_CALL_LIMITS = void 0;
+const better_sqlite3_1 = __importDefault(require("better-sqlite3"));
+const path_1 = __importDefault(require("path"));
+const os_1 = __importDefault(require("os"));
+const fs_1 = __importDefault(require("fs"));
+const crypto_1 = require("crypto");
+// Monthly call quotas per plan (matches synoi/domain PLAN_LIMITS)
+exports.PLAN_CALL_LIMITS = {
+    FREE: 10_000,
+    GROWTH: 100_000,
+    SCALE: 1_000_000,
+    ENTERPRISE: 10_000_000,
+};
+// RPM limits per plan
+exports.PLAN_RPM = {
+    FREE: 20,
+    GROWTH: 200,
+    SCALE: 2_000,
+    ENTERPRISE: 20_000,
+};
+// ─── KeyStore ─────────────────────────────────────────────────────────────────
+class KeyStore {
+    db;
+    constructor(dbPath) {
+        fs_1.default.mkdirSync(path_1.default.dirname(dbPath), { recursive: true });
+        this.db = new better_sqlite3_1.default(dbPath);
+        this.db.pragma('journal_mode = WAL');
+        this._migrate();
+    }
+    _migrate() {
+        this.db.exec(`
+      CREATE TABLE IF NOT EXISTS tenant_keys (
+        key_hash   TEXT PRIMARY KEY,
+        tenant_id  TEXT NOT NULL,
+        label      TEXT NOT NULL DEFAULT '',
+        plan       TEXT NOT NULL DEFAULT 'FREE',
+        created_at INTEGER NOT NULL,
+        last_used  INTEGER NOT NULL DEFAULT 0,
+        revoked    INTEGER NOT NULL DEFAULT 0,
+        profile_id TEXT
+      );
+
+      CREATE INDEX IF NOT EXISTS idx_tenant_id ON tenant_keys(tenant_id);
+
+      CREATE TABLE IF NOT EXISTS key_usage (
+        tenant_id    TEXT PRIMARY KEY,
+        total_calls  INTEGER NOT NULL DEFAULT 0,
+        cache_hits   INTEGER NOT NULL DEFAULT 0,
+        cache_misses INTEGER NOT NULL DEFAULT 0,
+        tokens_saved INTEGER NOT NULL DEFAULT 0,
+        savings_usd  REAL    NOT NULL DEFAULT 0,
+        updated_at   INTEGER NOT NULL DEFAULT 0
+      );
+
+      CREATE TABLE IF NOT EXISTS monthly_calls (
+        tenant_id  TEXT    NOT NULL,
+        month      TEXT    NOT NULL,   -- YYYY-MM
+        call_count INTEGER NOT NULL DEFAULT 0,
+        PRIMARY KEY (tenant_id, month)
+      );
+    `);
+        // Add plan column to existing databases (idempotent)
+        try {
+            this.db.exec(`ALTER TABLE tenant_keys ADD COLUMN plan TEXT NOT NULL DEFAULT 'FREE'`);
+        }
+        catch { /* column already exists */ }
+        // profile_id: nullable, references profiles.id. NULL = use tenant's active
+        // profile. Per-token binding lands in PR 3 (device-pairing flow).
+        try {
+            this.db.exec(`ALTER TABLE tenant_keys ADD COLUMN profile_id TEXT`);
+        }
+        catch { /* column already exists */ }
+    }
+    // ── Issue ──────────────────────────────────────────────────────────────────
+    /**
+     * Mint a new tenant license key.
+     *
+     * `opts.tenant_id` lets the caller bind the key to a pre-existing tenant
+     * (e.g. 'founder' for the operator's own gateway, or a tenant resolved from
+     * an admin-approved device-flow). Default behavior — when omitted — derives
+     * a fresh tenant_id from the key hash so every issued key is its own tenant.
+     *
+     * `opts.profile_id` binds the key to a specific gateway profile at issuance
+     * (PR 4 — edge device pairing). When set, the auth layer surfaces this on
+     * req.auth.profile_id and the credential cascade uses that profile directly
+     * instead of falling back to tenant_active_profile.
+     */
+    issueKey(label, plan = 'FREE', opts = {}) {
+        const raw = (0, crypto_1.randomBytes)(32).toString('hex');
+        const key = `synoi-sk-${raw}`;
+        const key_hash = hashKey(key);
+        const tenant_id = opts.tenant_id?.trim() || `t_${key_hash.slice(0, 16)}`;
+        const profile_id = opts.profile_id?.trim() || null;
+        const now = Date.now();
+        this.db.prepare(`
+      INSERT INTO tenant_keys (key_hash, tenant_id, label, plan, created_at, last_used, profile_id)
+      VALUES (?, ?, ?, ?, ?, ?, ?)
+    `).run(key_hash, tenant_id, label, plan, now, now, profile_id);
+        this.db.prepare(`
+      INSERT OR IGNORE INTO key_usage (tenant_id, updated_at) VALUES (?, ?)
+    `).run(tenant_id, now);
+        return { key, tenant_id, profile_id };
+    }
+    /**
+     * Hydrate a tenant_keys row from a remote (control-plane) validation. Idempotent
+     * by key_hash — first call INSERTs, subsequent calls UPDATE the bookkeeping
+     * fields. Used by the auth middleware to cache CP-issued licenses on first
+     * sight so subsequent requests don't pay the network roundtrip.
+     *
+     * `revoked` is NOT cleared on upsert — once a key is locally revoked the only
+     * way back is an explicit issuance. CP-side revocations propagate via short
+     * cache TTLs + periodic re-validation; see [license-client.ts] for the
+     * eviction cadence.
+     */
+    upsertFromRemote(key, fields) {
+        // Accept a gateway tenant key (synoi-sk-) or a control-plane license
+        // (synoi-lk-). The key is stored hashed and only used as an opaque
+        // tenant-resolution + cache-scope handle, so either prefix is valid here.
+        if (!key.startsWith('synoi-sk-') && !key.startsWith('synoi-lk-')) {
+            throw new Error('upsertFromRemote: not a synoi-sk-* or synoi-lk-* key');
+        }
+        const key_hash = hashKey(key);
+        const plan = fields.plan ?? 'FREE';
+        const profile_id = fields.profile_id ?? null;
+        const label = fields.label ?? 'remote-sync';
+        const now = Date.now();
+        this.db.prepare(`
+      INSERT INTO tenant_keys (key_hash, tenant_id, label, plan, created_at, last_used, profile_id)
+      VALUES (?, ?, ?, ?, ?, ?, ?)
+      ON CONFLICT(key_hash) DO UPDATE SET
+        tenant_id  = excluded.tenant_id,
+        plan       = excluded.plan,
+        profile_id = excluded.profile_id,
+        last_used  = excluded.last_used
+    `).run(key_hash, fields.tenant_id, label, plan, now, now, profile_id);
+        this.db.prepare(`
+      INSERT OR IGNORE INTO key_usage (tenant_id, updated_at) VALUES (?, ?)
+    `).run(fields.tenant_id, now);
+    }
+    // ── Validate ───────────────────────────────────────────────────────────────
+    validate(key) {
+        if (!key.startsWith('synoi-sk-') && !key.startsWith('synoi-lk-'))
+            return null;
+        const key_hash = hashKey(key);
+        const row = this.db.prepare(`
+      SELECT tenant_id, label, plan, revoked, profile_id FROM tenant_keys WHERE key_hash = ?
+    `).get(key_hash);
+        if (!row || row.revoked)
+            return null;
+        this.db.prepare(`
+      UPDATE tenant_keys SET last_used = ? WHERE key_hash = ?
+    `).run(Date.now(), key_hash);
+        return { tenant_id: row.tenant_id, label: row.label, plan: row.plan, profile_id: row.profile_id ?? null };
+    }
+    // ── Revoke ─────────────────────────────────────────────────────────────────
+    revoke(key) {
+        const key_hash = hashKey(key);
+        const result = this.db.prepare(`
+      UPDATE tenant_keys SET revoked = 1 WHERE key_hash = ? AND revoked = 0
+    `).run(key_hash);
+        return result.changes > 0;
+    }
+    // ── Usage ──────────────────────────────────────────────────────────────────
+    recordCall(tenant_id, hit, tokens_saved = 0, savings_usd = 0) {
+        const now = Date.now();
+        this.db.prepare(`
+      INSERT INTO key_usage (tenant_id, total_calls, cache_hits, cache_misses, tokens_saved, savings_usd, updated_at)
+      VALUES (?, 1, ?, ?, ?, ?, ?)
+      ON CONFLICT(tenant_id) DO UPDATE SET
+        total_calls  = total_calls  + 1,
+        cache_hits   = cache_hits   + excluded.cache_hits,
+        cache_misses = cache_misses + excluded.cache_misses,
+        tokens_saved = tokens_saved + excluded.tokens_saved,
+        savings_usd  = savings_usd  + excluded.savings_usd,
+        updated_at   = excluded.updated_at
+    `).run(tenant_id, hit ? 1 : 0, hit ? 0 : 1, tokens_saved, savings_usd, now);
+    }
+    /**
+     * Attribute token usage to a tenant WITHOUT incrementing the call counter.
+     * Used by the streaming path (M1): the request was already counted by
+     * recordCall at cache-miss time, but the token counts are only known once the
+     * stream ends. This folds those tokens into the metering totals without
+     * double-counting the call.
+     */
+    recordStreamUsage(tenant_id, tokens, savings_usd = 0) {
+        const now = Date.now();
+        this.db.prepare(`
+      INSERT INTO key_usage (tenant_id, total_calls, cache_hits, cache_misses, tokens_saved, savings_usd, updated_at)
+      VALUES (?, 0, 0, 0, ?, ?, ?)
+      ON CONFLICT(tenant_id) DO UPDATE SET
+        tokens_saved = tokens_saved + excluded.tokens_saved,
+        savings_usd  = savings_usd  + excluded.savings_usd,
+        updated_at   = excluded.updated_at
+    `).run(tenant_id, Math.max(0, tokens), savings_usd, now);
+    }
+    getUsage(tenant_id) {
+        return this.db.prepare(`
+      SELECT * FROM key_usage WHERE tenant_id = ?
+    `).get(tenant_id);
+    }
+    // ── Plan management ────────────────────────────────────────────────────────
+    setPlan(tenant_id, plan) {
+        this.db.prepare(`UPDATE tenant_keys SET plan = ? WHERE tenant_id = ?`).run(plan, tenant_id);
+    }
+    getPlan(tenant_id) {
+        const row = this.db.prepare(`SELECT plan FROM tenant_keys WHERE tenant_id = ? LIMIT 1`).get(tenant_id);
+        return row?.plan ?? 'FREE';
+    }
+    // ── Monthly quota ──────────────────────────────────────────────────────────
+    _currentMonth() {
+        return new Date().toISOString().slice(0, 7); // YYYY-MM
+    }
+    getMonthlyCallCount(tenant_id) {
+        const month = this._currentMonth();
+        const row = this.db.prepare(`SELECT call_count FROM monthly_calls WHERE tenant_id = ? AND month = ?`).get(tenant_id, month);
+        return row?.call_count ?? 0;
+    }
+    incrementMonthlyCallCount(tenant_id) {
+        const month = this._currentMonth();
+        this.db.prepare(`
+      INSERT INTO monthly_calls (tenant_id, month, call_count) VALUES (?, ?, 1)
+      ON CONFLICT(tenant_id, month) DO UPDATE SET call_count = call_count + 1
+    `).run(tenant_id, month);
+        return this.getMonthlyCallCount(tenant_id);
+    }
+    isMonthlyQuotaExceeded(tenant_id, plan) {
+        const limit = exports.PLAN_CALL_LIMITS[plan];
+        return this.getMonthlyCallCount(tenant_id) >= limit;
+    }
+    listKeys(tenant_id) {
+        return this.db.prepare(`
+      SELECT key_hash, tenant_id, label, created_at, last_used, revoked
+      FROM tenant_keys WHERE tenant_id = ?
+    `).all(tenant_id);
+    }
+}
+exports.KeyStore = KeyStore;
+// ─── Singleton ────────────────────────────────────────────────────────────────
+const DATA_DIR = process.env.SYNOI_DATA_DIR ?? path_1.default.join(os_1.default.homedir(), '.synoi', 'gateway');
+const DB_PATH = path_1.default.join(DATA_DIR, '_keys', 'keys.db');
+exports.keyStore = new KeyStore(DB_PATH);
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+function hashKey(key) {
+    return (0, crypto_1.createHash)('sha256').update(key).digest('hex');
+}

package/dist/native-mldsa.js

@@ -0,0 +1,82 @@
+"use strict";
+/**
+ * native-mldsa.ts — ML-DSA-65 verification with a native node:crypto fast path.
+ *
+ * When the runtime ships OpenSSL 3.5+ (Node 24+), node:crypto exposes a native
+ * `ml-dsa-65` key type whose verify is ~7.8x faster than the pure-JS
+ * @noble/post-quantum implementation (~207us vs ~1.6ms; measured on Node
+ * 24.16.0 / OpenSSL 3.5.6). This helper feature-detects native support ONCE and
+ * routes the gateway's verify-bound paths (verify-router, skill-signature
+ * verify) accordingly, with a transparent @noble fallback on older runtimes.
+ *
+ * Both paths are byte-for-byte interoperable: a signature minted by either
+ * implementation verifies identically under the other (cross-impl KAT lives in
+ * @synoi/sraid test/mldsa-kat.test.ts). The native path is a transparent
+ * performance swap, NOT a behavior change. Node < 24 keeps working unchanged.
+ *
+ * Verify-only: signing stays on @noble so the existing seed-derived key
+ * lifecycle is untouched. Takes a RAW 1952-byte ML-DSA-65 public key and a RAW
+ * signature, matching the @noble surface.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isNativeMlDsaAvailable = isNativeMlDsaAvailable;
+exports.verifyMlDsa65 = verifyMlDsa65;
+const node_crypto_1 = require("node:crypto");
+const ml_dsa_js_1 = require("@noble/post-quantum/ml-dsa.js");
+// Fixed SubjectPublicKeyInfo DER prefix for ML-DSA-65 (id-ml-dsa-65 =
+// 2.16.840.1.101.3.4.3.18); the only variable part is the 1952-byte key.
+const MLDSA65_SPKI_PREFIX = Buffer.from('308207b2300b0609608648016503040312038207a100', 'hex');
+const MLDSA65_PUBKEY_LEN = 1952;
+let nativeAvailable;
+function detectNative() {
+    if (nativeAvailable !== undefined)
+        return nativeAvailable;
+    try {
+        const dummy = Buffer.concat([MLDSA65_SPKI_PREFIX, Buffer.alloc(MLDSA65_PUBKEY_LEN)]);
+        const ko = (0, node_crypto_1.createPublicKey)({ key: dummy, format: 'der', type: 'spki' });
+        nativeAvailable = ko.asymmetricKeyType === 'ml-dsa-65';
+    }
+    catch {
+        nativeAvailable = false;
+    }
+    return nativeAvailable;
+}
+/** True when ML-DSA-65 verify runs on native node:crypto, false on @noble. */
+function isNativeMlDsaAvailable() {
+    return detectNative();
+}
+const keyCache = new Map();
+function keyObjectFromRaw(raw) {
+    if (raw.length !== MLDSA65_PUBKEY_LEN) {
+        throw new Error(`ml-dsa-65 public key must be ${MLDSA65_PUBKEY_LEN} bytes`);
+    }
+    const hex = Buffer.from(raw).toString('hex');
+    let ko = keyCache.get(hex);
+    if (!ko) {
+        const der = Buffer.concat([MLDSA65_SPKI_PREFIX, Buffer.from(raw)]);
+        ko = (0, node_crypto_1.createPublicKey)({ key: der, format: 'der', type: 'spki' });
+        keyCache.set(hex, ko);
+    }
+    return ko;
+}
+/**
+ * Verify a raw ML-DSA-65 signature over `message` against a raw 1952-byte
+ * public key. Native node:crypto when available, otherwise @noble. Returns
+ * false (never throws) on any malformed input or verification failure.
+ */
+function verifyMlDsa65(signature, message, publicKeyRaw) {
+    if (detectNative()) {
+        try {
+            return (0, node_crypto_1.verify)(null, message, keyObjectFromRaw(publicKeyRaw), signature);
+        }
+        catch {
+            return false;
+        }
+    }
+    try {
+        return ml_dsa_js_1.ml_dsa65.verify(signature, message, publicKeyRaw);
+    }
+    catch {
+        return false;
+    }
+}