@sunaiva/gate 1.1.2 → 1.1.4

package/dist/identity/nudge.js

@@ -0,0 +1,74 @@
+/**
+ * First-run nudge — opt-in registration prompt.
+ *
+ * Design constraints (v1.1.4):
+ *   - CORE gate is FREE and NEVER email-gated. Gating the critical path = lockout class.
+ *   - Email is captured at the VALUE layer (live rule feed, Shield-of-Health dashboard).
+ *   - Nudge is skippable via SUNAIVA_NUDGE_OFF=1.
+ *   - Nudge fires at most once per install (presence of ~/.sunaiva-gate/registered marker).
+ *   - FAIL-OPEN: any error in this module must not surface to the caller.
+ */
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+const MARKER_DIR = join(homedir(), ".sunaiva-gate");
+const MARKER_PATH = join(MARKER_DIR, "registered");
+/**
+ * Returns true if the registration marker exists (user has already seen the nudge).
+ */
+export function isNudgeComplete() {
+    try {
+        return existsSync(MARKER_PATH);
+    }
+    catch {
+        return true; // fail-open: if we can't read, skip the nudge
+    }
+}
+/**
+ * Writes the registration marker so the nudge does not fire again.
+ * Fail-open on any error.
+ */
+export function markNudgeComplete() {
+    try {
+        if (!existsSync(MARKER_DIR)) {
+            mkdirSync(MARKER_DIR, { recursive: true });
+        }
+        writeFileSync(MARKER_PATH, new Date().toISOString(), "utf-8");
+    }
+    catch {
+        // fail-open: marker write failure is non-fatal
+    }
+}
+/**
+ * maybeShowNudge — print a friendly one-time registration prompt if:
+ *   1. SUNAIVA_NUDGE_OFF=1 is NOT set
+ *   2. The registered marker does not exist
+ *   3. stdout is a TTY (not piped — avoids polluting JSON output)
+ *
+ * FAIL-OPEN: any error is swallowed. This function NEVER throws.
+ */
+export function maybeShowNudge() {
+    try {
+        if (process.env.SUNAIVA_NUDGE_OFF === "1")
+            return;
+        if (isNudgeComplete())
+            return;
+        // Only print to TTY to avoid polluting piped/MCP output
+        if (!process.stdout.isTTY) {
+            // In non-TTY mode write to stderr so the nudge does not break JSON output
+            process.stderr.write(`[sunaiva-gate] Register free at https://sunaivacore.io/gate/register ` +
+                `for the live rule feed + Shield-of-Health dashboard. ` +
+                `Skip with SUNAIVA_NUDGE_OFF=1.\n`);
+        }
+        else {
+            process.stdout.write(`\n[sunaiva-gate] Register free at https://sunaivacore.io/gate/register\n` +
+                `  for the live rule feed + Shield-of-Health dashboard.\n` +
+                `  Skip this message with: SUNAIVA_NUDGE_OFF=1\n\n`);
+        }
+        markNudgeComplete();
+    }
+    catch {
+        // fail-open: nudge errors are never surfaced
+    }
+}
+//# sourceMappingURL=nudge.js.map

package/dist/identity/nudge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"nudge.js","sourceRoot":"","sources":["../../src/identity/nudge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAC/D,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,MAAM,UAAU,GAAG,IAAI,CAAC,OAAO,EAAE,EAAE,eAAe,CAAC,CAAC;AACpD,MAAM,WAAW,GAAG,IAAI,CAAC,UAAU,EAAE,YAAY,CAAC,CAAC;AAEnD;;GAEG;AACH,MAAM,UAAU,eAAe;IAC7B,IAAI,CAAC;QACH,OAAO,UAAU,CAAC,WAAW,CAAC,CAAC;IACjC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC,CAAC,8CAA8C;IAC7D,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,iBAAiB;IAC/B,IAAI,CAAC;QACH,IAAI,CAAC,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC;YAC5B,SAAS,CAAC,UAAU,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAC7C,CAAC;QACD,aAAa,CAAC,WAAW,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,EAAE,OAAO,CAAC,CAAC;IAChE,CAAC;IAAC,MAAM,CAAC;QACP,+CAA+C;IACjD,CAAC;AACH,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,cAAc;IAC5B,IAAI,CAAC;QACH,IAAI,OAAO,CAAC,GAAG,CAAC,iBAAiB,KAAK,GAAG;YAAE,OAAO;QAClD,IAAI,eAAe,EAAE;YAAE,OAAO;QAC9B,wDAAwD;QACxD,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;YAC1B,0EAA0E;YAC1E,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,uEAAuE;gBACrE,uDAAuD;gBACvD,kCAAkC,CACrC,CAAC;QACJ,CAAC;aAAM,CAAC;YACN,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,0EAA0E;gBACxE,0DAA0D;gBAC1D,mDAAmD,CACtD,CAAC;QACJ,CAAC;QACD,iBAAiB,EAAE,CAAC;IACtB,CAAC;IAAC,MAAM,CAAC;QACP,6CAA6C;IAC/C,CAAC;AACH,CAAC"}

package/dist/identity/premium-unlock.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Premium rule unlock — fetch premium rules from backend when API key is present.
+ *
+ * Design constraints (v1.1.4):
+ *   - Endpoint TBD: stubbed via SUNAIVA_RULES_ENDPOINT env var.
+ *   - Default stub: https://sunaivacore.io/api/rules/premium (backend TBD).
+ *   - On success: merges premium rules into the engine's in-memory rule set.
+ *   - On any failure: falls back to local-only rules + logs to stderr.
+ *   - 10s timeout — premium rules are fetched once at startup, not per-request.
+ *   - FAIL-OPEN: a network failure never blocks the user from using the gate.
+ *   - Only called when config.api_key is present (non-empty string).
+ */
+import type { Rule } from "../engine/rule-engine.js";
+export interface PremiumUnlockResult {
+    ok: boolean;
+    rules_fetched: number;
+    error?: string;
+}
+/**
+ * fetchPremiumRules — GET premium rules from the backend using the API key.
+ *
+ * On success: returns the rule array for the caller to merge into the engine.
+ * On any failure: returns fail-open result (ok:false, rules_fetched:0).
+ * NEVER throws.
+ */
+export declare function fetchPremiumRules(apiKey: string): Promise<{
+    result: PremiumUnlockResult;
+    rules: Rule[];
+}>;
+//# sourceMappingURL=premium-unlock.d.ts.map

package/dist/identity/premium-unlock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"premium-unlock.d.ts","sourceRoot":"","sources":["../../src/identity/premium-unlock.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,0BAA0B,CAAC;AAKrD,MAAM,WAAW,mBAAmB;IAClC,EAAE,EAAE,OAAO,CAAC;IACZ,aAAa,EAAE,MAAM,CAAC;IACtB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;GAMG;AACH,wBAAsB,iBAAiB,CACrC,MAAM,EAAE,MAAM,GACb,OAAO,CAAC;IAAE,MAAM,EAAE,mBAAmB,CAAC;IAAC,KAAK,EAAE,IAAI,EAAE,CAAA;CAAE,CAAC,CAoDzD"}

package/dist/identity/premium-unlock.js

@@ -0,0 +1,65 @@
+/**
+ * Premium rule unlock — fetch premium rules from backend when API key is present.
+ *
+ * Design constraints (v1.1.4):
+ *   - Endpoint TBD: stubbed via SUNAIVA_RULES_ENDPOINT env var.
+ *   - Default stub: https://sunaivacore.io/api/rules/premium (backend TBD).
+ *   - On success: merges premium rules into the engine's in-memory rule set.
+ *   - On any failure: falls back to local-only rules + logs to stderr.
+ *   - 10s timeout — premium rules are fetched once at startup, not per-request.
+ *   - FAIL-OPEN: a network failure never blocks the user from using the gate.
+ *   - Only called when config.api_key is present (non-empty string).
+ */
+const DEFAULT_RULES_ENDPOINT = "https://sunaivacore.io/api/rules/premium";
+const FETCH_TIMEOUT_MS = 10_000;
+/**
+ * fetchPremiumRules — GET premium rules from the backend using the API key.
+ *
+ * On success: returns the rule array for the caller to merge into the engine.
+ * On any failure: returns fail-open result (ok:false, rules_fetched:0).
+ * NEVER throws.
+ */
+export async function fetchPremiumRules(apiKey) {
+    if (!apiKey || apiKey.trim().length === 0) {
+        return {
+            result: { ok: false, rules_fetched: 0, error: "empty api_key" },
+            rules: [],
+        };
+    }
+    const endpoint = process.env.SUNAIVA_RULES_ENDPOINT ?? DEFAULT_RULES_ENDPOINT;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+    try {
+        const response = await fetch(endpoint, {
+            method: "GET",
+            headers: {
+                Authorization: `Bearer ${apiKey}`,
+                "Accept": "application/json",
+                "X-Gate-Version": "1.1.4",
+            },
+            signal: controller.signal,
+        });
+        clearTimeout(timer);
+        if (!response.ok) {
+            const errMsg = `premium-unlock: backend returned ${response.status}`;
+            console.error(`[sunaiva-gate] ${errMsg} — falling back to local-only rules`);
+            return { result: { ok: false, rules_fetched: 0, error: errMsg }, rules: [] };
+        }
+        const data = (await response.json());
+        const rules = Array.isArray(data.rules) ? data.rules : [];
+        return {
+            result: { ok: true, rules_fetched: rules.length },
+            rules,
+        };
+    }
+    catch (err) {
+        clearTimeout(timer);
+        const errMsg = err instanceof Error ? err.message : String(err);
+        console.error(`[sunaiva-gate] premium-unlock fetch failed (fail-OPEN): ${errMsg} — local-only rules active`);
+        return {
+            result: { ok: false, rules_fetched: 0, error: errMsg },
+            rules: [],
+        };
+    }
+}
+//# sourceMappingURL=premium-unlock.js.map

package/dist/identity/premium-unlock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"premium-unlock.js","sourceRoot":"","sources":["../../src/identity/premium-unlock.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,MAAM,sBAAsB,GAAG,0CAA0C,CAAC;AAC1E,MAAM,gBAAgB,GAAG,MAAM,CAAC;AAQhC;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,MAAc;IAEd,IAAI,CAAC,MAAM,IAAI,MAAM,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC1C,OAAO;YACL,MAAM,EAAE,EAAE,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE,CAAC,EAAE,KAAK,EAAE,eAAe,EAAE;YAC/D,KAAK,EAAE,EAAE;SACV,CAAC;IACJ,CAAC;IAED,MAAM,QAAQ,GACZ,OAAO,CAAC,GAAG,CAAC,sBAAsB,IAAI,sBAAsB,CAAC;IAE/D,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;IACzC,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,EAAE,EAAE,gBAAgB,CAAC,CAAC;IAErE,IAAI,CAAC;QACH,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,QAAQ,EAAE;YACrC,MAAM,EAAE,KAAK;YACb,OAAO,EAAE;gBACP,aAAa,EAAE,UAAU,MAAM,EAAE;gBACjC,QAAQ,EAAE,kBAAkB;gBAC5B,gBAAgB,EAAE,OAAO;aAC1B;YACD,MAAM,EAAE,UAAU,CAAC,MAAM;SAC1B,CAAC,CAAC;QAEH,YAAY,CAAC,KAAK,CAAC,CAAC;QAEpB,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;YACjB,MAAM,MAAM,GAAG,oCAAoC,QAAQ,CAAC,MAAM,EAAE,CAAC;YACrE,OAAO,CAAC,KAAK,CAAC,kBAAkB,MAAM,qCAAqC,CAAC,CAAC;YAC7E,OAAO,EAAE,MAAM,EAAE,EAAE,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC;QAC/E,CAAC;QAED,MAAM,IAAI,GAAG,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAuB,CAAC;QAC3D,MAAM,KAAK,GAAW,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;QAElE,OAAO;YACL,MAAM,EAAE,EAAE,EAAE,EAAE,IAAI,EAAE,aAAa,EAAE,KAAK,CAAC,MAAM,EAAE;YACjD,KAAK;SACN,CAAC;IACJ,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,YAAY,CAAC,KAAK,CAAC,CAAC;QACpB,MAAM,MAAM,GACV,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACnD,OAAO,CAAC,KAAK,CACX,2DAA2D,MAAM,4BAA4B,CAC9F,CAAC;QACF,OAAO;YACL,MAAM,EAAE,EAAE,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE;YACtD,KAAK,EAAE,EAAE;SACV,CAAC;IACJ,CAAC;AACH,CAAC"}

package/dist/identity/register-client.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Registration client — POST {email} to the Sunaiva registration endpoint.
+ *
+ * Design constraints (v1.1.4):
+ *   - Endpoint TBD: stubbed via SUNAIVA_REGISTER_ENDPOINT env var.
+ *   - Default stub: https://sunaivacore.io/api/register (backend TBD).
+ *   - Returns {api_key, ok} or throws — CALLER must catch and fail-open.
+ *   - 5s timeout to avoid hanging in tool-use critical paths.
+ *   - NEVER includes PII beyond the email the user voluntarily supplies.
+ *   - FAIL-OPEN: caller wraps in try/catch.
+ */
+export interface RegisterResult {
+    ok: boolean;
+    api_key?: string;
+    message?: string;
+}
+/**
+ * registerEmail — POST {email} to the registration endpoint.
+ *
+ * Throws on network error, non-2xx, or timeout. Caller must catch and fail-open.
+ *
+ * @param email  User email (voluntarily supplied at value capture layer).
+ */
+export declare function registerEmail(email: string): Promise<RegisterResult>;
+//# sourceMappingURL=register-client.d.ts.map

package/dist/identity/register-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"register-client.d.ts","sourceRoot":"","sources":["../../src/identity/register-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAKH,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,OAAO,CAAC;IACZ,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;GAMG;AACH,wBAAsB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,CAoC1E"}

package/dist/identity/register-client.js

@@ -0,0 +1,48 @@
+/**
+ * Registration client — POST {email} to the Sunaiva registration endpoint.
+ *
+ * Design constraints (v1.1.4):
+ *   - Endpoint TBD: stubbed via SUNAIVA_REGISTER_ENDPOINT env var.
+ *   - Default stub: https://sunaivacore.io/api/register (backend TBD).
+ *   - Returns {api_key, ok} or throws — CALLER must catch and fail-open.
+ *   - 5s timeout to avoid hanging in tool-use critical paths.
+ *   - NEVER includes PII beyond the email the user voluntarily supplies.
+ *   - FAIL-OPEN: caller wraps in try/catch.
+ */
+const DEFAULT_REGISTER_ENDPOINT = "https://sunaivacore.io/api/register";
+const REGISTER_TIMEOUT_MS = 5_000;
+/**
+ * registerEmail — POST {email} to the registration endpoint.
+ *
+ * Throws on network error, non-2xx, or timeout. Caller must catch and fail-open.
+ *
+ * @param email  User email (voluntarily supplied at value capture layer).
+ */
+export async function registerEmail(email) {
+    const endpoint = process.env.SUNAIVA_REGISTER_ENDPOINT ?? DEFAULT_REGISTER_ENDPOINT;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), REGISTER_TIMEOUT_MS);
+    try {
+        const response = await fetch(endpoint, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ email, source: "sunaiva-gate", version: "1.1.4" }),
+            signal: controller.signal,
+        });
+        clearTimeout(timer);
+        if (!response.ok) {
+            throw new Error(`Registration endpoint returned ${response.status}`);
+        }
+        const data = (await response.json());
+        return {
+            ok: true,
+            api_key: data.api_key,
+            message: data.message,
+        };
+    }
+    catch (err) {
+        clearTimeout(timer);
+        throw err; // re-throw so caller can fail-open
+    }
+}
+//# sourceMappingURL=register-client.js.map

package/dist/identity/register-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"register-client.js","sourceRoot":"","sources":["../../src/identity/register-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,MAAM,yBAAyB,GAAG,qCAAqC,CAAC;AACxE,MAAM,mBAAmB,GAAG,KAAK,CAAC;AAQlC;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,KAAa;IAC/C,MAAM,QAAQ,GACZ,OAAO,CAAC,GAAG,CAAC,yBAAyB,IAAI,yBAAyB,CAAC;IAErE,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;IACzC,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,EAAE,EAAE,mBAAmB,CAAC,CAAC;IAExE,IAAI,CAAC;QACH,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,QAAQ,EAAE;YACrC,MAAM,EAAE,MAAM;YACd,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;YAC/C,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,cAAc,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC;YACzE,MAAM,EAAE,UAAU,CAAC,MAAM;SAC1B,CAAC,CAAC;QAEH,YAAY,CAAC,KAAK,CAAC,CAAC;QAEpB,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;YACjB,MAAM,IAAI,KAAK,CAAC,kCAAkC,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC;QACvE,CAAC;QAED,MAAM,IAAI,GAAG,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,CAIlC,CAAC;QAEF,OAAO;YACL,EAAE,EAAE,IAAI;YACR,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,OAAO,EAAE,IAAI,CAAC,OAAO;SACtB,CAAC;IACJ,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,YAAY,CAAC,KAAK,CAAC,CAAC;QACpB,MAAM,GAAG,CAAC,CAAC,mCAAmC;IAChD,CAAC;AACH,CAAC"}

package/dist/identity/telemetry.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Opt-in anonymous telemetry emit + install-tracking layer.
+ *
+ * Design constraints (v1.1.4):
+ *   - NO PII, NO file content, NO action content.
+ *   - Emits: version, gate_version, agent type, os.platform(), os.release(), counts.
+ *   - Off by default: only fires when user has opted in (SUNAIVA_TELEMETRY_ON=1).
+ *   - Kill-switch: SUNAIVA_TELEMETRY_OFF=1 overrides any opt-in.
+ *   - 2s timeout — telemetry must never delay gate decisions.
+ *   - FAIL-OPEN: any error is swallowed. This function NEVER throws.
+ *   - Endpoint stubbed via SUNAIVA_TELEMETRY_ENDPOINT env var.
+ *
+ * Install-tracking layer (v1.1.4 additions):
+ *   - anonymousFingerprint(): SHA-256 of stable machine identifiers. NO PII, NO IP.
+ *   - isGenesisInternal(): detects Genesis development environment.
+ *   - emitFirstRunIfNeeded(): single-shot install event, fire-and-forget. 3s timeout.
+ *     Opt-out: SUNAIVA_GATE_TELEMETRY=0 disables completely.
+ *     Marker: ~/.sunaiva-gate/first-run.json prevents duplicate events.
+ */
+export interface TelemetryEvent {
+    /** Gate version emitting this event */
+    gate_version: string;
+    /** Agent type (claude-code, cursor, etc.) or "unknown" */
+    agent: string;
+    /** os.platform() — linux, win32, darwin */
+    os_platform: string;
+    /** os.release() — kernel version */
+    os_release: string;
+    /** Number of violations in the evaluation (no content) */
+    violation_count: number;
+    /** Number of warnings in the evaluation (no content) */
+    warning_count: number;
+    /** Number of rules active in this session */
+    active_rule_count: number;
+    /** ISO timestamp */
+    ts: string;
+}
+/**
+ * emitEvaluation — send an anonymous telemetry event.
+ *
+ * Only fires when SUNAIVA_TELEMETRY_ON=1 AND SUNAIVA_TELEMETRY_OFF is not set.
+ * FAIL-OPEN: all errors are swallowed. Never throws. Never awaited by caller
+ * in a blocking way (fire-and-forget via void).
+ */
+export declare function emitEvaluation(eventSummary: {
+    agent: string;
+    violation_count: number;
+    warning_count: number;
+    active_rule_count: number;
+}): void;
+/**
+ * emitFirstRunIfNeeded — fire a single anonymous "first_run" install event.
+ *
+ * Privacy posture:
+ *   - Payload contains: event="first_run", anonymous fingerprint (32-hex),
+ *     gate_version, node_version, os_platform, os_release,
+ *     is_genesis_internal, timestamp. NO PII, NO IP, NO email.
+ *   - Runs at most once per machine (marker file ~/.sunaiva-gate/first-run.json).
+ *   - Opt-out: SUNAIVA_GATE_TELEMETRY=0 disables entirely.
+ *   - Fire-and-forget: caller must NOT await. Never throws, never logs to stderr.
+ *   - 3-second timeout — must not delay gate startup.
+ */
+export declare function emitFirstRunIfNeeded(version: string): Promise<void>;
+//# sourceMappingURL=telemetry.d.ts.map

package/dist/identity/telemetry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry.d.ts","sourceRoot":"","sources":["../../src/identity/telemetry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAkBH,MAAM,WAAW,cAAc;IAC7B,uCAAuC;IACvC,YAAY,EAAE,MAAM,CAAC;IACrB,0DAA0D;IAC1D,KAAK,EAAE,MAAM,CAAC;IACd,2CAA2C;IAC3C,WAAW,EAAE,MAAM,CAAC;IACpB,oCAAoC;IACpC,UAAU,EAAE,MAAM,CAAC;IACnB,0DAA0D;IAC1D,eAAe,EAAE,MAAM,CAAC;IACxB,wDAAwD;IACxD,aAAa,EAAE,MAAM,CAAC;IACtB,6CAA6C;IAC7C,iBAAiB,EAAE,MAAM,CAAC;IAC1B,oBAAoB;IACpB,EAAE,EAAE,MAAM,CAAC;CACZ;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,YAAY,EAAE;IAC3C,KAAK,EAAE,MAAM,CAAC;IACd,eAAe,EAAE,MAAM,CAAC;IACxB,aAAa,EAAE,MAAM,CAAC;IACtB,iBAAiB,EAAE,MAAM,CAAC;CAC3B,GAAG,IAAI,CAUP;AAuFD;;;;;;;;;;;GAWG;AACH,wBAAsB,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CA0CzE"}

package/dist/identity/telemetry.js

@@ -0,0 +1,173 @@
+/**
+ * Opt-in anonymous telemetry emit + install-tracking layer.
+ *
+ * Design constraints (v1.1.4):
+ *   - NO PII, NO file content, NO action content.
+ *   - Emits: version, gate_version, agent type, os.platform(), os.release(), counts.
+ *   - Off by default: only fires when user has opted in (SUNAIVA_TELEMETRY_ON=1).
+ *   - Kill-switch: SUNAIVA_TELEMETRY_OFF=1 overrides any opt-in.
+ *   - 2s timeout — telemetry must never delay gate decisions.
+ *   - FAIL-OPEN: any error is swallowed. This function NEVER throws.
+ *   - Endpoint stubbed via SUNAIVA_TELEMETRY_ENDPOINT env var.
+ *
+ * Install-tracking layer (v1.1.4 additions):
+ *   - anonymousFingerprint(): SHA-256 of stable machine identifiers. NO PII, NO IP.
+ *   - isGenesisInternal(): detects Genesis development environment.
+ *   - emitFirstRunIfNeeded(): single-shot install event, fire-and-forget. 3s timeout.
+ *     Opt-out: SUNAIVA_GATE_TELEMETRY=0 disables completely.
+ *     Marker: ~/.sunaiva-gate/first-run.json prevents duplicate events.
+ */
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { homedir, hostname, platform, release, userInfo, } from "node:os";
+import { join } from "node:path";
+const GATE_VERSION = "1.1.4";
+const DEFAULT_TELEMETRY_ENDPOINT = "https://gate-telemetry.kinan-ae7.workers.dev/v1/events";
+const TELEMETRY_TIMEOUT_MS = 2_000;
+/**
+ * emitEvaluation — send an anonymous telemetry event.
+ *
+ * Only fires when SUNAIVA_TELEMETRY_ON=1 AND SUNAIVA_TELEMETRY_OFF is not set.
+ * FAIL-OPEN: all errors are swallowed. Never throws. Never awaited by caller
+ * in a blocking way (fire-and-forget via void).
+ */
+export function emitEvaluation(eventSummary) {
+    // Kill-switch always wins
+    if (process.env.SUNAIVA_TELEMETRY_OFF === "1")
+        return;
+    // Must be explicitly opted in — off by default (CORE is free, no data harvesting)
+    if (process.env.SUNAIVA_TELEMETRY_ON !== "1")
+        return;
+    // Fire-and-forget — do not await, do not block gate decisions
+    void _sendTelemetry(eventSummary).catch(() => {
+        // fail-open: swallow all errors
+    });
+}
+async function _sendTelemetry(eventSummary) {
+    const endpoint = process.env.SUNAIVA_TELEMETRY_ENDPOINT ?? DEFAULT_TELEMETRY_ENDPOINT;
+    const payload = {
+        gate_version: GATE_VERSION,
+        agent: eventSummary.agent,
+        os_platform: platform(),
+        os_release: release(),
+        violation_count: eventSummary.violation_count,
+        warning_count: eventSummary.warning_count,
+        active_rule_count: eventSummary.active_rule_count,
+        ts: new Date().toISOString(),
+    };
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), TELEMETRY_TIMEOUT_MS);
+    try {
+        await fetch(endpoint, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify(payload),
+            signal: controller.signal,
+        });
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+// ---------------------------------------------------------------------------
+// Install-tracking layer (v1.1.4)
+// ---------------------------------------------------------------------------
+const FIRST_RUN_TIMEOUT_MS = 3_000;
+const FIRST_RUN_MARKER_DIR = join(homedir(), ".sunaiva-gate");
+const FIRST_RUN_MARKER_PATH = join(FIRST_RUN_MARKER_DIR, "first-run.json");
+/**
+ * anonymousFingerprint — derive a stable, anonymous machine identifier.
+ *
+ * Privacy posture:
+ *   - Input: hostname + username + platform + homedir (all local, no network).
+ *   - Output: first 32 hex chars of SHA-256 — sufficient to de-duplicate
+ *     installs, NOT sufficient to reverse-identify a user.
+ *   - NO IP address, NO email, NO file paths, NO system serial numbers.
+ *   - Value is stable across gate upgrades on the same machine.
+ *   - On error returns "unknown" (fail-open).
+ */
+function anonymousFingerprint() {
+    try {
+        const raw = [
+            hostname(),
+            userInfo().username,
+            platform(),
+            homedir(),
+        ].join("|");
+        return createHash("sha256").update(raw).digest("hex").slice(0, 32);
+    }
+    catch {
+        return "unknown";
+    }
+}
+/**
+ * isGenesisInternal — returns true when running inside a Genesis development
+ * environment.
+ *
+ * Privacy posture:
+ *   - Reads only environment variables, no network calls.
+ *   - Allows the telemetry receiver to filter Genesis-internal noise from
+ *     real-world install events without any PII signal.
+ */
+function isGenesisInternal() {
+    if (process.env.SUNAIVA_GATE_INTERNAL)
+        return true;
+    if (process.env.GENESIS_SESSION_ID)
+        return true;
+    const projectDir = process.env.CLAUDE_PROJECT_DIR ?? "";
+    if (projectDir.includes("genesis-system"))
+        return true;
+    return false;
+}
+/**
+ * emitFirstRunIfNeeded — fire a single anonymous "first_run" install event.
+ *
+ * Privacy posture:
+ *   - Payload contains: event="first_run", anonymous fingerprint (32-hex),
+ *     gate_version, node_version, os_platform, os_release,
+ *     is_genesis_internal, timestamp. NO PII, NO IP, NO email.
+ *   - Runs at most once per machine (marker file ~/.sunaiva-gate/first-run.json).
+ *   - Opt-out: SUNAIVA_GATE_TELEMETRY=0 disables entirely.
+ *   - Fire-and-forget: caller must NOT await. Never throws, never logs to stderr.
+ *   - 3-second timeout — must not delay gate startup.
+ */
+export async function emitFirstRunIfNeeded(version) {
+    try {
+        // Respect explicit opt-out
+        if (process.env.SUNAIVA_GATE_TELEMETRY === "0")
+            return;
+        // Single-shot per machine
+        if (existsSync(FIRST_RUN_MARKER_PATH))
+            return;
+        const payload = {
+            event: "first_run",
+            fingerprint: anonymousFingerprint(),
+            gate_version: version,
+            node_version: process.version,
+            os_platform: platform(),
+            os_release: release(),
+            is_genesis_internal: isGenesisInternal(),
+            timestamp: new Date().toISOString(),
+        };
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), FIRST_RUN_TIMEOUT_MS);
+        try {
+            await fetch(DEFAULT_TELEMETRY_ENDPOINT, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify(payload),
+                signal: controller.signal,
+            });
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        // Write marker only after a successful (non-throwing) POST attempt
+        mkdirSync(FIRST_RUN_MARKER_DIR, { recursive: true });
+        writeFileSync(FIRST_RUN_MARKER_PATH, JSON.stringify({ first_run_at: new Date().toISOString() }));
+    }
+    catch {
+        // FAIL-OPEN: telemetry must never surface errors to the caller.
+    }
+}
+//# sourceMappingURL=telemetry.js.map

package/dist/identity/telemetry.js.map

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

package/dist/index.js

@@ -12,10 +12,14 @@ import { ShipConfidenceGate } from "./engine/ship-confidence-gate.js";
 import { evaluateAction } from "./engine/rule-engine.js";
 import { getConstitutionalRuleIds } from "./engine/immutability.js";
 import { DEFAULT_CONFIG } from "./config/defaults.js";
+import { runBridge } from "./events/bridge.js";
+import { SUPPORTED_AGENTS } from "./installer/detect.js";
+import { maybeShowNudge } from "./identity/nudge.js";
+import { emitFirstRunIfNeeded } from "./identity/first-run.js";
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { fileURLToPath } from "node:url";
-const PKG_VERSION = "1.1.2";
+const PKG_VERSION = "1.1.4";
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const server = new Server({ name: "sunaiva-gate", version: PKG_VERSION }, { capabilities: { tools: {} } });
 server.setRequestHandler(ListToolsRequestSchema, async () => ({
@@ -61,6 +65,9 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
     ],
 }));
 server.setRequestHandler(CallToolRequestSchema, async (req) => {
+    // Fire-and-forget first-run ping (MCP server path only — never --smoke-test,
+    // --version, or --mcp-bridge). Self-throttles via marker file after first call.
+    void emitFirstRunIfNeeded(PKG_VERSION);
     const { name, arguments: args } = req.params;
     try {
         switch (name) {
@@ -256,6 +263,73 @@ Support: support@sunaiva.ai`);
     if (argv.includes("--smoke-test")) {
         process.exit(runSmokeTest());
     }
+    // --mcp-bridge <agent> — production hook path.
+    // Every installer shim runs `npx @sunaiva/gate --mcp-bridge <agent>`.
+    // The host agent pipes a raw JSON event to stdin; we evaluate it through
+    // the wired rule engine (via runBridge → handleValidateAction) and write
+    // the verdict JSON to stdout. Exit 0 always (fail-OPEN contract: a gate
+    // error must never crash the host agent).
+    const bridgeIdx = argv.indexOf("--mcp-bridge");
+    if (bridgeIdx !== -1) {
+        // v1.1.4: show first-run nudge (fail-open, skippable via SUNAIVA_NUDGE_OFF=1)
+        maybeShowNudge();
+        const agentArg = argv[bridgeIdx + 1];
+        if (!agentArg || !SUPPORTED_AGENTS.includes(agentArg)) {
+            const supported = SUPPORTED_AGENTS.join(", ");
+            console.error(`[sunaiva-gate v${PKG_VERSION}] --mcp-bridge requires a valid agent name (${supported})`);
+            // Fail-OPEN: print an allow envelope so the host can continue.
+            console.log(JSON.stringify({
+                ok: true,
+                event: "unknown",
+                source_agent: agentArg ?? "unknown",
+                tool: undefined,
+                action: undefined,
+                session_id: undefined,
+                decision: "allow",
+                reason: "invalid agent argument — fail-OPEN",
+                fail_open: true,
+                gate_version: PKG_VERSION,
+            }));
+            process.exit(0);
+        }
+        // Read the raw event payload from stdin (the host pipes it in one shot).
+        let raw = null;
+        try {
+            const chunks = [];
+            for await (const chunk of process.stdin) {
+                chunks.push(chunk);
+            }
+            const text = Buffer.concat(chunks).toString("utf-8").trim();
+            if (text.length > 0) {
+                raw = JSON.parse(text);
+            }
+        }
+        catch {
+            // Malformed or empty stdin: fall through with raw=null; runBridge/
+            // normalizeIncoming handles unknown shapes gracefully (fail-OPEN).
+        }
+        try {
+            const verdict = await runBridge(raw, agentArg, PKG_VERSION);
+            console.log(JSON.stringify(verdict));
+        }
+        catch (err) {
+            // runBridge promises never to throw, but be defensive anyway.
+            console.error(`[sunaiva-gate v${PKG_VERSION}] bridge unexpected error (fail-OPEN):`, err instanceof Error ? err.message : String(err));
+            console.log(JSON.stringify({
+                ok: true,
+                event: "unknown",
+                source_agent: agentArg,
+                tool: undefined,
+                action: undefined,
+                session_id: undefined,
+                decision: "allow",
+                reason: `bridge unexpected error (fail-OPEN): ${err instanceof Error ? err.message : String(err)}`,
+                fail_open: true,
+                gate_version: PKG_VERSION,
+            }));
+        }
+        process.exit(0);
+    }
     // --ship-confidence <artifact-id> — standalone CLI gate invocation.
     // Exit 0 = allow, 2 = block, 3 = internal error (fail-OPEN logged).
     // Owned by B2; documented by B5.