@sunaiva/gate 1.0.0 → 1.1.0

package/dist/engine/backend-client.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Backend client for the Sunaiva Gate premium tier.
+ *
+ * Responsibilities:
+ *   - POST to `<backend_url>` for each premium (`[server-side]`) rule.
+ *   - Fail-OPEN for the *customer*: any backend failure (network, timeout,
+ *     5xx, 401, missing token) results in the rule being SKIPPED, never
+ *     a customer-side block. A Sunaiva outage MUST NOT take down a
+ *     customer's agent pipeline.
+ *   - Emit a once-per-process stderr notice when premium rules are skipped
+ *     because no API token is configured. Subsequent skips in the same
+ *     process are silent.
+ *   - One retry with 500ms backoff on 5xx / network error (per spec).
+ *   - Request timeout default 3000ms, env-overridable.
+ *   - Track audit counters: every skipped rule appears in
+ *     `BackendEvalResult.skipped_rule_ids` with a status code in
+ *     `BackendRuleResult.status` (e.g. `skipped_premium`, `skipped_auth`)
+ *     so the audit ledger can record exactly why a rule was deferred.
+ *
+ * What this module does NOT do:
+ *   - It does NOT decide whether to call the backend at all. That is the
+ *     caller's job (rule-engine.ts checks rule.backend_required + URL).
+ *   - It does NOT block. The returned result is informational; the caller
+ *     turns matched=true with severity=block into a customer-side block.
+ *   - It does NOT mutate global state apart from the once-per-process
+ *     stderr flag.
+ */
+import { BackendClientOptions, BackendEvalResult } from "../types/backend.js";
+/**
+ * Reset the once-per-process notice flag. Test-only — wired so that test
+ * fixtures can assert that the notice fires on the first call but not on
+ * subsequent calls within the same process.
+ */
+export declare function resetPremiumSkippedNotice(): void;
+/**
+ * Returns true iff the once-per-process notice was emitted. Test-only.
+ */
+export declare function wasPremiumSkippedNoticeShown(): boolean;
+export declare class BackendClient {
+    private readonly url;
+    private readonly apiToken;
+    private readonly timeoutMs;
+    private readonly fetchImpl;
+    constructor(options?: BackendClientOptions);
+    /** True iff the client has an API token configured. */
+    isConfigured(): boolean;
+    /**
+     * Evaluate a list of premium rules against `inputText`. Returns one
+     * BackendRuleResult per requested rule. Never throws; backend errors
+     * become `skipped_*` statuses so the caller can fail-OPEN gracefully.
+     */
+    evaluate(ruleIds: string[], inputText: string, context?: Record<string, unknown>): Promise<BackendEvalResult>;
+    /** Single-rule call with retry + timeout. */
+    private evaluateOne;
+    /** Single HTTP call. Returns a tagged outcome — never throws on HTTP. */
+    private callOnce;
+}
+//# sourceMappingURL=backend-client.d.ts.map

package/dist/engine/backend-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"backend-client.d.ts","sourceRoot":"","sources":["../../src/engine/backend-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EACL,oBAAoB,EACpB,iBAAiB,EAMlB,MAAM,qBAAqB,CAAC;AAM7B;;;;GAIG;AACH,wBAAgB,yBAAyB,IAAI,IAAI,CAEhD;AAED;;GAEG;AACH,wBAAgB,4BAA4B,IAAI,OAAO,CAEtD;AAuBD,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;IAC7B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAgB;IACzC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAe;gBAE7B,OAAO,GAAE,oBAAyB;IAqB9C,uDAAuD;IACvD,YAAY,IAAI,OAAO;IAIvB;;;;OAIG;IACG,QAAQ,CACZ,OAAO,EAAE,MAAM,EAAE,EACjB,SAAS,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAChC,OAAO,CAAC,iBAAiB,CAAC;IA8C7B,6CAA6C;YAC/B,WAAW;IA4DzB,yEAAyE;YAC3D,QAAQ;CAmFvB"}

package/dist/engine/backend-client.js

@@ -0,0 +1,287 @@
+/**
+ * Backend client for the Sunaiva Gate premium tier.
+ *
+ * Responsibilities:
+ *   - POST to `<backend_url>` for each premium (`[server-side]`) rule.
+ *   - Fail-OPEN for the *customer*: any backend failure (network, timeout,
+ *     5xx, 401, missing token) results in the rule being SKIPPED, never
+ *     a customer-side block. A Sunaiva outage MUST NOT take down a
+ *     customer's agent pipeline.
+ *   - Emit a once-per-process stderr notice when premium rules are skipped
+ *     because no API token is configured. Subsequent skips in the same
+ *     process are silent.
+ *   - One retry with 500ms backoff on 5xx / network error (per spec).
+ *   - Request timeout default 3000ms, env-overridable.
+ *   - Track audit counters: every skipped rule appears in
+ *     `BackendEvalResult.skipped_rule_ids` with a status code in
+ *     `BackendRuleResult.status` (e.g. `skipped_premium`, `skipped_auth`)
+ *     so the audit ledger can record exactly why a rule was deferred.
+ *
+ * What this module does NOT do:
+ *   - It does NOT decide whether to call the backend at all. That is the
+ *     caller's job (rule-engine.ts checks rule.backend_required + URL).
+ *   - It does NOT block. The returned result is informational; the caller
+ *     turns matched=true with severity=block into a customer-side block.
+ *   - It does NOT mutate global state apart from the once-per-process
+ *     stderr flag.
+ */
+import { DEFAULT_BACKEND_URL, DEFAULT_TIMEOUT_MS, MAX_RETRIES, RETRY_BACKOFF_MS, } from "../types/backend.js";
+// Once-per-process flag for the "no API token" stderr notice. Module-level
+// so that multiple instances of BackendClient in the same process share it.
+let _premiumSkippedNoticeShown = false;
+/**
+ * Reset the once-per-process notice flag. Test-only — wired so that test
+ * fixtures can assert that the notice fires on the first call but not on
+ * subsequent calls within the same process.
+ */
+export function resetPremiumSkippedNotice() {
+    _premiumSkippedNoticeShown = false;
+}
+/**
+ * Returns true iff the once-per-process notice was emitted. Test-only.
+ */
+export function wasPremiumSkippedNoticeShown() {
+    return _premiumSkippedNoticeShown;
+}
+/** Stderr notice format — exact string per the brief. */
+function emitOnceSessionNoticeNoToken() {
+    if (_premiumSkippedNoticeShown)
+        return;
+    _premiumSkippedNoticeShown = true;
+    // Brief specifies the exact substring:
+    //   "[sunaiva-gate] premium rules skipped — set SUNAIVA_GATE_API_TOKEN to enable.
+    //    See https://sunaivadigital.com/pricing"
+    console.error("[sunaiva-gate] premium rules skipped — set SUNAIVA_GATE_API_TOKEN to enable. " +
+        "See https://sunaivadigital.com/pricing");
+}
+/**
+ * Sleep helper for retry backoff. Pulled out so tests can mock it via the
+ * fetchImpl path (the test fixture controls the call count, not the clock).
+ */
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+export class BackendClient {
+    url;
+    apiToken;
+    timeoutMs;
+    fetchImpl;
+    constructor(options = {}) {
+        this.url =
+            options.url ??
+                process.env.SUNAIVA_GATE_BACKEND_URL ??
+                DEFAULT_BACKEND_URL;
+        this.apiToken =
+            options.apiToken ?? process.env.SUNAIVA_GATE_API_TOKEN ?? null;
+        const envTimeout = process.env.SUNAIVA_GATE_BACKEND_TIMEOUT_MS;
+        const envTimeoutParsed = envTimeout ? Number.parseInt(envTimeout, 10) : NaN;
+        this.timeoutMs =
+            options.timeoutMs ??
+                (Number.isFinite(envTimeoutParsed) && envTimeoutParsed > 0
+                    ? envTimeoutParsed
+                    : DEFAULT_TIMEOUT_MS);
+        // Default to the platform fetch. Node 18+ ships native fetch.
+        this.fetchImpl = options.fetchImpl ?? globalThis.fetch;
+    }
+    /** True iff the client has an API token configured. */
+    isConfigured() {
+        return !!this.apiToken;
+    }
+    /**
+     * Evaluate a list of premium rules against `inputText`. Returns one
+     * BackendRuleResult per requested rule. Never throws; backend errors
+     * become `skipped_*` statuses so the caller can fail-OPEN gracefully.
+     */
+    async evaluate(ruleIds, inputText, context) {
+        const t0 = Date.now();
+        // Fast-path: no token configured → all rules skipped, once-per-process notice.
+        if (!this.apiToken) {
+            emitOnceSessionNoticeNoToken();
+            const results = ruleIds.map((id) => ({
+                rule_id: id,
+                status: "skipped_no_token",
+                matched: false,
+                latency_ms: 0,
+                error: "no API token (set SUNAIVA_GATE_API_TOKEN)",
+            }));
+            return {
+                evaluated_rules: ruleIds,
+                results,
+                matched_rule_ids: [],
+                skipped_rule_ids: [...ruleIds],
+                latency_ms: Date.now() - t0,
+                premium_skipped_due_to_no_token: true,
+            };
+        }
+        // Sequential calls — the backend is per-rule. Could be parallelised in
+        // a future version; sequential is fine for v1.1.0 because premium rule
+        // counts per validate() call are bounded by the active_rules set.
+        const results = [];
+        for (const ruleId of ruleIds) {
+            results.push(await this.evaluateOne(ruleId, inputText, context));
+        }
+        const matched_rule_ids = results.filter((r) => r.matched).map((r) => r.rule_id);
+        const skipped_rule_ids = results
+            .filter((r) => r.status.startsWith("skipped_"))
+            .map((r) => r.rule_id);
+        return {
+            evaluated_rules: ruleIds,
+            results,
+            matched_rule_ids,
+            skipped_rule_ids,
+            latency_ms: Date.now() - t0,
+            premium_skipped_due_to_no_token: false,
+        };
+    }
+    /** Single-rule call with retry + timeout. */
+    async evaluateOne(ruleId, inputText, context) {
+        const t0 = Date.now();
+        let lastError;
+        let lastStatus;
+        for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+            try {
+                const outcome = await this.callOnce(ruleId, inputText, context);
+                // If callOnce returned a non-retriable result (2xx or 4xx-except-5xx),
+                // return immediately. Retry only on 5xx / network failure.
+                if (outcome.kind === "ok") {
+                    return {
+                        rule_id: ruleId,
+                        status: outcome.body.matched ? "matched" : "no_match",
+                        matched: outcome.body.matched,
+                        severity: outcome.body.severity,
+                        decision: outcome.body.decision,
+                        reason: outcome.body.reason,
+                        http_status: outcome.status,
+                        latency_ms: Date.now() - t0,
+                    };
+                }
+                if (outcome.kind === "client_error") {
+                    // 4xx (other than 5xx) — do NOT retry. Map to a skipped status.
+                    return {
+                        rule_id: ruleId,
+                        status: clientErrorToStatus(outcome.status),
+                        matched: false,
+                        http_status: outcome.status,
+                        error: outcome.errorBody?.error ?? `HTTP ${outcome.status}`,
+                        latency_ms: Date.now() - t0,
+                    };
+                }
+                // 5xx or network: capture and fall through to retry / final return.
+                lastError = outcome.errorMessage;
+                lastStatus = outcome.status;
+            }
+            catch (e) {
+                // Unexpected exception in callOnce itself. Treat as retriable network failure.
+                lastError = e instanceof Error ? e.message : String(e);
+            }
+            if (attempt < MAX_RETRIES) {
+                await sleep(RETRY_BACKOFF_MS);
+            }
+        }
+        // Exhausted retries — fail-OPEN (skipped).
+        return {
+            rule_id: ruleId,
+            status: "skipped_error",
+            matched: false,
+            http_status: lastStatus,
+            error: lastError ?? "backend unreachable after retries",
+            latency_ms: Date.now() - t0,
+        };
+    }
+    /** Single HTTP call. Returns a tagged outcome — never throws on HTTP. */
+    async callOnce(ruleId, inputText, context) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+        try {
+            const resp = await this.fetchImpl(this.url, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    Authorization: `Bearer ${this.apiToken}`,
+                    "User-Agent": "sunaiva-gate-client/1.1.0",
+                },
+                body: JSON.stringify({
+                    rule_id: ruleId,
+                    input_text: inputText,
+                    context: context ?? {},
+                }),
+                signal: controller.signal,
+            });
+            // 2xx → parse body, even if response is something we don't expect.
+            // Backend contract: { matched, severity, decision, reason? }
+            if (resp.status >= 200 && resp.status < 300) {
+                let body;
+                try {
+                    body = (await resp.json());
+                }
+                catch (e) {
+                    // Malformed 2xx — treat as a server fault, retry.
+                    return {
+                        kind: "server_error",
+                        status: resp.status,
+                        errorMessage: `malformed JSON body: ${e instanceof Error ? e.message : String(e)}`,
+                    };
+                }
+                if (typeof body?.matched !== "boolean") {
+                    return {
+                        kind: "server_error",
+                        status: resp.status,
+                        errorMessage: "missing 'matched' field in backend response",
+                    };
+                }
+                return { kind: "ok", status: resp.status, body };
+            }
+            if (resp.status >= 500 && resp.status < 600) {
+                let errorBody;
+                try {
+                    errorBody = (await resp.json());
+                }
+                catch {
+                    // Ignore — body may be empty/text.
+                }
+                return {
+                    kind: "server_error",
+                    status: resp.status,
+                    errorMessage: errorBody?.error ?? `HTTP ${resp.status}`,
+                };
+            }
+            // 4xx — client error, not retriable.
+            let errorBody;
+            try {
+                errorBody = (await resp.json());
+            }
+            catch {
+                // Ignore.
+            }
+            return { kind: "client_error", status: resp.status, errorBody };
+        }
+        catch (e) {
+            // AbortError (timeout) or network failure. Both retriable.
+            const msg = e instanceof Error ? e.message : String(e);
+            return {
+                kind: "server_error",
+                status: undefined,
+                errorMessage: msg.includes("aborted") ? "request timeout" : msg,
+            };
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+}
+/** Map a 4xx status to a BackendEvalStatus. */
+function clientErrorToStatus(status) {
+    switch (status) {
+        case 401:
+            return "skipped_auth";
+        case 402:
+            return "skipped_tier";
+        case 404:
+            return "skipped_unknown";
+        case 429:
+            return "skipped_quota";
+        default:
+            return "skipped_error";
+    }
+}
+//# sourceMappingURL=backend-client.js.map

package/dist/engine/backend-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"backend-client.js","sourceRoot":"","sources":["../../src/engine/backend-client.ts"],"names":[],"mappings":"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"}

package/dist/engine/hmac-verifier.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Canonical JSON encoding — recursive sorted keys, tight separators.
+ *
+ * Output bytes are IDENTICAL to Python's
+ *   json.dumps(obj, sort_keys=True, separators=(",", ":")).encode()
+ *
+ * Restrictions / assumptions (matching Python json defaults):
+ *   - Object keys are strings.
+ *   - Numbers are serialized via JSON.stringify (matches Python for integers
+ *     and finite floats with no scientific notation under 1e21).
+ *   - Strings use Python's ensure_ascii=True semantics (default in json.dumps):
+ *     non-ASCII chars are escaped as \uXXXX. UTF-8 byte equality is preserved
+ *     because the escaped form is pure ASCII.
+ *   - Functions, undefined, and Symbols are not allowed (would not round-trip
+ *     to/from Python).
+ */
+export declare function canonicalJson(value: unknown): Buffer;
+/**
+ * HMAC-SHA256 verification with constant-time comparison.
+ *
+ * @param payload  Canonical-JSON bytes of the verdict (minus signature field).
+ * @param signatureHex  The signature provided in the verdict, hex-encoded.
+ * @param key  The raw signing key bytes (UTF-8 encoded from the env var).
+ * @returns true iff the signature is valid; false otherwise (including any
+ *   length-mismatch error from timingSafeEqual which would throw — caught and
+ *   returned as false to maintain a uniform predicate contract).
+ */
+export declare function verifyHmac(payload: Buffer, signatureHex: string, key: Buffer): boolean;
+/**
+ * Convenience: sign a payload buffer with a key. Used in tests.
+ */
+export declare function signPayload(payload: Buffer, key: Buffer): string;
+//# sourceMappingURL=hmac-verifier.d.ts.map

package/dist/engine/hmac-verifier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hmac-verifier.d.ts","sourceRoot":"","sources":["../../src/engine/hmac-verifier.ts"],"names":[],"mappings":"AAuBA;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAEpD;AAkFD;;;;;;;;;GASG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAUtF;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAEhE"}

package/dist/engine/hmac-verifier.js

@@ -0,0 +1,161 @@
+/**
+ * HMAC-SHA256 verifier + canonical JSON helpers.
+ *
+ * BYTE-FOR-BYTE compatible with Python's:
+ *   json.dumps(obj, sort_keys=True, separators=(",", ":")).encode()
+ *   hmac.new(key, payload, hashlib.sha256).hexdigest()
+ *   hmac.compare_digest(expected, given)
+ *
+ * Reference: sunaiva-ship-confidence/utils/signing.py
+ *            .claude/hooks/ship_confidence_gate.py (_canonical_json, _verify_hmac)
+ *
+ * Why a custom canonicalizer (not JSON.stringify-with-replacer):
+ *   - Python's json.dumps sorts keys at EVERY level (recursive).
+ *   - Python uses NO spaces between separators with (",", ":").
+ *   - JavaScript's default JSON.stringify preserves insertion order, not sorted.
+ *   - Python escapes
+/
+ by default; we don't need that for HMAC
+ *     payloads in practice because the verdict objects are ASCII-only, but the
+ *     canonicalizer matches Python's escape rules for the common case.
+ */
+import { createHmac, timingSafeEqual } from "node:crypto";
+/**
+ * Canonical JSON encoding — recursive sorted keys, tight separators.
+ *
+ * Output bytes are IDENTICAL to Python's
+ *   json.dumps(obj, sort_keys=True, separators=(",", ":")).encode()
+ *
+ * Restrictions / assumptions (matching Python json defaults):
+ *   - Object keys are strings.
+ *   - Numbers are serialized via JSON.stringify (matches Python for integers
+ *     and finite floats with no scientific notation under 1e21).
+ *   - Strings use Python's ensure_ascii=True semantics (default in json.dumps):
+ *     non-ASCII chars are escaped as \uXXXX. UTF-8 byte equality is preserved
+ *     because the escaped form is pure ASCII.
+ *   - Functions, undefined, and Symbols are not allowed (would not round-trip
+ *     to/from Python).
+ */
+export function canonicalJson(value) {
+    return Buffer.from(canonicalize(value), "utf-8");
+}
+function canonicalize(value) {
+    if (value === null)
+        return "null";
+    if (typeof value === "boolean")
+        return value ? "true" : "false";
+    if (typeof value === "number") {
+        if (!Number.isFinite(value)) {
+            // Python emits NaN/Infinity but it's not valid JSON; refuse.
+            throw new Error("Cannot canonicalize non-finite number");
+        }
+        // For integers, JSON.stringify matches Python json.dumps exactly.
+        // For floats Python may emit differently than JS in edge cases; verdict
+        // payloads do not use floats for signed fields, so this is acceptable.
+        return JSON.stringify(value);
+    }
+    if (typeof value === "string") {
+        return encodeString(value);
+    }
+    if (Array.isArray(value)) {
+        const parts = value.map((v) => canonicalize(v));
+        return "[" + parts.join(",") + "]";
+    }
+    if (typeof value === "object") {
+        const obj = value;
+        const keys = Object.keys(obj).sort();
+        const parts = [];
+        for (const k of keys) {
+            // Match Python: skip undefined values to align with the typical pattern
+            // of "exclude unset" in Pydantic model_dump. NB: Python json.dumps would
+            // RAISE on a None value missing in a dict — it never sees undefined.
+            // We treat undefined as "omit" to be ergonomic; null is emitted as "null".
+            if (obj[k] === undefined)
+                continue;
+            parts.push(encodeString(k) + ":" + canonicalize(obj[k]));
+        }
+        return "{" + parts.join(",") + "}";
+    }
+    throw new Error(`Cannot canonicalize value of type ${typeof value}`);
+}
+/**
+ * String encoding matching Python json.dumps default behaviour
+ * (ensure_ascii=True). Non-ASCII characters are escaped as \uXXXX so the
+ * output is pure ASCII — byte-equal under any UTF-8 round-trip.
+ *
+ * Standard ASCII escapes: \b \t \n \f \r \" \\ — same as JS JSON.stringify.
+ * Control chars < 0x20 → \u00XX.
+ * Non-ASCII (≥ 0x80) → \uXXXX (or surrogate pair for code points > 0xFFFF).
+ */
+function encodeString(s) {
+    let out = '"';
+    for (let i = 0; i < s.length; i++) {
+        const c = s.charCodeAt(i);
+        if (c === 0x22) {
+            out += '\\"';
+        }
+        else if (c === 0x5c) {
+            out += "\\\\";
+        }
+        else if (c === 0x08) {
+            out += "\\b";
+        }
+        else if (c === 0x0c) {
+            out += "\\f";
+        }
+        else if (c === 0x0a) {
+            out += "\\n";
+        }
+        else if (c === 0x0d) {
+            out += "\\r";
+        }
+        else if (c === 0x09) {
+            out += "\\t";
+        }
+        else if (c < 0x20) {
+            out += "\\u" + c.toString(16).padStart(4, "0");
+        }
+        else if (c < 0x7f) {
+            // ASCII printable — emit as-is.
+            out += s[i];
+        }
+        else {
+            // Non-ASCII — emit as \uXXXX. For chars in the BMP this is the code unit
+            // directly; surrogate pairs are emitted as two \uXXXX sequences, which
+            // matches Python json.dumps with ensure_ascii=True.
+            out += "\\u" + c.toString(16).padStart(4, "0");
+        }
+    }
+    out += '"';
+    return out;
+}
+/**
+ * HMAC-SHA256 verification with constant-time comparison.
+ *
+ * @param payload  Canonical-JSON bytes of the verdict (minus signature field).
+ * @param signatureHex  The signature provided in the verdict, hex-encoded.
+ * @param key  The raw signing key bytes (UTF-8 encoded from the env var).
+ * @returns true iff the signature is valid; false otherwise (including any
+ *   length-mismatch error from timingSafeEqual which would throw — caught and
+ *   returned as false to maintain a uniform predicate contract).
+ */
+export function verifyHmac(payload, signatureHex, key) {
+    try {
+        const expectedHex = createHmac("sha256", key).update(payload).digest("hex");
+        if (expectedHex.length !== signatureHex.length)
+            return false;
+        const a = Buffer.from(expectedHex, "utf-8");
+        const b = Buffer.from(signatureHex, "utf-8");
+        return timingSafeEqual(a, b);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Convenience: sign a payload buffer with a key. Used in tests.
+ */
+export function signPayload(payload, key) {
+    return createHmac("sha256", key).update(payload).digest("hex");
+}
+//# sourceMappingURL=hmac-verifier.js.map

package/dist/engine/hmac-verifier.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hmac-verifier.js","sourceRoot":"","sources":["../../src/engine/hmac-verifier.ts"],"names":[],"mappings":"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"}

package/dist/engine/immutability.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Immutability guard — constitutional rules cannot be disabled or bypassed.
+ *
+ * Builder B4. Resolves CRITICAL findings:
+ *   - C2: `update_rules({disable: ['fin-001']})` must reject (cannot disable constitutional).
+ *   - C3: `log_bypass({rule_id: 'fin-001'})` must reject (cannot bypass constitutional).
+ *
+ * Design:
+ *   - Single canonical source of truth for "what is constitutional":
+ *       1. CONSTITUTIONAL_RULE_IDS (frozen array in src/config/defaults.ts) — primary.
+ *       2. Cross-check against loadConstitutionalRulesOnly() from rule-engine — defense in depth.
+ *       Union of both => guard set. This means a future rule with `enforcement === "constitutional"`
+ *       in rules.json is automatically protected even if CONSTITUTIONAL_RULE_IDS isn't updated.
+ *   - assertCanDisable() and assertCanBypass() throw ConstitutionalImmutableError.
+ *   - enforceConstitutionalActive() returns a config with every constitutional ID guaranteed
+ *     in active_rules — called on every config load so user tampering of ~/.sunaiva/gate-config.json
+ *     cannot disable a constitutional rule.
+ *
+ * Why both sources?
+ *   - CONSTITUTIONAL_RULE_IDS in defaults.ts is the frozen, code-level source — even if
+ *     the bundled rules.json is missing or corrupt, we still know which IDs are protected.
+ *   - loadConstitutionalRulesOnly() from rule-engine reads from the package-bundled rules,
+ *     never user config — adds new rules without code changes if rules.json is updated.
+ *   - Union ensures additive protection: a rule listed EITHER place is constitutional.
+ */
+import { type GateConfig } from "../config/defaults.js";
+export declare class ConstitutionalImmutableError extends Error {
+    readonly rule_id: string;
+    readonly op: "disable" | "bypass";
+    constructor(ruleId: string, op: "disable" | "bypass");
+}
+/**
+ * Returns the canonical set of constitutional rule IDs. Union of:
+ *   1. CONSTITUTIONAL_RULE_IDS (frozen array — code-level guarantee)
+ *   2. loadConstitutionalRulesOnly() (rules.json — runtime additive)
+ *
+ * Cached after first call. Tests can force a refresh with refreshConstitutionalCache().
+ */
+export declare function getConstitutionalRuleIds(): ReadonlySet<string>;
+/**
+ * Test-only cache reset. Used by tests that mutate environment / config files
+ * and need a fresh read.
+ */
+export declare function refreshConstitutionalCache(): void;
+export declare function isConstitutional(ruleId: string): boolean;
+export declare function assertCanDisable(ruleId: string): void;
+export declare function assertCanBypass(ruleId: string): void;
+/**
+ * Returns a new GateConfig with every constitutional rule ID guaranteed
+ * in active_rules. The on-disk config file is NOT mutated; this is an
+ * in-memory enforcement layer so a user can hand-edit `~/.sunaiva/gate-config.json`
+ * to remove constitutional rules and the next runtime load will simply
+ * re-add them — silently and unbypassably.
+ *
+ * Idempotent: calling on a config that already has all constitutional IDs
+ * is a no-op (returns a structurally equal config).
+ */
+export declare function enforceConstitutionalActive(config: GateConfig): GateConfig;
+//# sourceMappingURL=immutability.d.ts.map

package/dist/engine/immutability.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"immutability.d.ts","sourceRoot":"","sources":["../../src/engine/immutability.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,EAA2B,KAAK,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAOjF,qBAAa,4BAA6B,SAAQ,KAAK;IACrD,SAAgB,OAAO,EAAE,MAAM,CAAC;IAChC,SAAgB,EAAE,EAAE,SAAS,GAAG,QAAQ,CAAC;gBAE7B,MAAM,EAAE,MAAM,EAAE,EAAE,EAAE,SAAS,GAAG,QAAQ;CASrD;AAQD;;;;;;GAMG;AACH,wBAAgB,wBAAwB,IAAI,WAAW,CAAC,MAAM,CAAC,CAc9D;AAED;;;GAGG;AACH,wBAAgB,0BAA0B,IAAI,IAAI,CAEjD;AAMD,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAExD;AAMD,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAIrD;AAED,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAIpD;AAMD;;;;;;;;;GASG;AACH,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,UAAU,GAAG,UAAU,CAe1E"}