@cello-protocol/gateway 0.0.1

package/dist/types.d.ts

@@ -0,0 +1,121 @@
+/**
+ * @cello-protocol/gateway — the security gateway contract.
+ *
+ * The gateway is a SEPARATE program from the daemon (M9-CORE-001 / V3 split-deployment).
+ * The daemon holds ONLY this interface and its two call sites; all detection lives in the
+ * gateway program. The same interface backs both the local sidecar (Phase 1) and the
+ * remote mTLS gateway (Phase 2) — Phase 2 is a transport swap behind `SecurityGatewayClient`,
+ * not a rewrite.
+ *
+ * M9-CORE-001 implements the seam with a pass-through: every message is screened (the call
+ * happens at the two fixed points) but the verdict is always `allow`, except the fail-closed
+ * `block` a configured-but-unreachable gateway returns. Detectors and the redact/warn
+ * dispositions arrive in later stories (M9-IN-*, M9-OUT-*, M9-FEED-001).
+ */
+/** Which direction the content is flowing relative to the daemon. */
+export type ScreenDirection = "outbound" | "inbound";
+/**
+ * What the gateway decided to do with a message.
+ *
+ * - `allow`  — deliver/send as-is (or as transformed via `content`).
+ * - `block`  — do not deliver/send. M9-CORE-001 uses this only for fail-closed
+ *              (`gateway_unavailable`); detectors add real blocks later.
+ * - `redact` — deliver/send a transformed `content` (M9-OUT-* / M9-FEED-001).
+ * - `warn`   — held pending an explicit governance decision (M9-FEED-001).
+ *
+ * M9-CORE-001 only ever returns `allow` or `block`; `redact`/`warn` are declared here so the
+ * seam code that switches on the disposition is complete from the start.
+ */
+export type ScreenDisposition = "allow" | "block" | "redact" | "warn";
+/** The per-stage governance disposition (the §6 model: advisory, mutating, needs-decision, blocking). */
+export type GovernanceDisposition = "observe" | "redact" | "block" | "warn";
+/**
+ * A governance decision the agent attaches to a re-send to resolve a warned item (M9-FEED-001 §6):
+ *   - `redact`       — send with a typed placeholder. Always available (the agent's autonomous lever).
+ *   - `allow_once`   — send the value verbatim THIS once. Honored ONLY when `autonomous_override` is
+ *                      ON; OFF (default) → rejected + re-warned (the operator must whitelist).
+ *   - `allow_always` — persist the value to the whitelist (a config loosening → a human action:
+ *                      WebAuthn-confirmed + attested). Autonomous mode degrades to `allow_once` for
+ *                      THIS send and raises an operator whitelist-add request; OFF → rejected.
+ */
+export type GovernanceDecision = "redact" | "allow_once" | "allow_always";
+/**
+ * One governance finding published by a screen stage (§6). The verdict aggregates these; the daemon
+ * renders them to the agent (M9-FEED-001) — as the transformations on a redact, the reasons on a
+ * block, or the flagged items (with `flagId`) on a warn.
+ */
+export interface GovernanceEvent {
+    stage: string;
+    disposition: GovernanceDisposition;
+    category: string;
+    reason: string;
+    /** Deterministic handle the agent passes on a governance re-send (warn items). */
+    flagId?: string;
+}
+/** Context the daemon passes with each screen request. Identity-scoped, never content-derived. */
+export interface ScreenContext {
+    direction: ScreenDirection;
+    agentName: string;
+    sessionId: string;
+    /** The async-flow correlation id, threaded through every event in this send/receive (INV-7). */
+    correlationId?: string;
+    /**
+     * The agent's per-item decisions on a governance RE-SEND (M9-FEED-001 §6), keyed by the `flagId`
+     * the prior `warn` verdict returned. Stateless: the gateway re-scans the (full) content, re-derives
+     * the same deterministic flagIds, and applies these decisions. A flagId that no longer matches
+     * (content changed) is ignored and that item re-warns/redacts — a decision can never mis-apply to
+     * different content (SI-002). Omitted flags default to `redact`. Outbound only.
+     */
+    governanceDecisions?: Record<string, GovernanceDecision>;
+}
+/**
+ * A screening verdict.
+ *
+ * `content` is the bytes the daemon should act on: for `allow` it equals the input; for
+ * `redact` it is the transformed form; for `block`/`warn` it is absent (nothing is
+ * delivered/sent). `reason` is a stable machine code; `guidance` is actionable text the
+ * agent sees on a non-allow outcome (INV-7).
+ */
+export interface ScreenVerdict {
+    disposition: ScreenDisposition;
+    content?: Uint8Array;
+    reason?: string;
+    guidance?: string;
+    /** The governance findings behind this verdict (M9-FEED-001 renders them to the agent). */
+    events?: GovernanceEvent[];
+    /**
+     * Set on a `block` whose cause is the CONTENT itself — a detector rejected these exact bytes
+     * (inbound: a confident non-allowlisted language, a high-score injection; outbound likewise).
+     * Such a block is TERMINAL: redelivering the identical bytes would be rejected identically, so the
+     * inbound daemon must record the leaf + acknowledge (the sender stops) while never delivering it,
+     * NOT leave it un-acked for redelivery. A fail-closed block (`gateway_unavailable` /
+     * `governance_timeout`) and an internal `screen_error` are TRANSIENT — `terminal` is left unset so
+     * the daemon holds the content un-acked and the sender redelivers once the gateway recovers.
+     */
+    terminal?: boolean;
+}
+/**
+ * The narrow interface the daemon holds. Two methods, two seams:
+ *   - `screenOutbound` runs in `cello_send` before `sessionNodeManager.sendContent`.
+ *   - `screenInbound`  runs in the inbound funnel before content enters the receive buffer.
+ *
+ * Implementations MUST be non-hanging: every call resolves to a terminal verdict within a
+ * deadline. A timeout or unreachable gateway resolves to a fail-closed `block`
+ * (`gateway_unavailable`), never a rejected/never-settling promise (INV-6 / SI-001).
+ */
+export interface SecurityGatewayClient {
+    screenOutbound(content: Uint8Array, ctx: ScreenContext): Promise<ScreenVerdict>;
+    screenInbound(content: Uint8Array, ctx: ScreenContext): Promise<ScreenVerdict>;
+}
+/** The reason code a fail-closed verdict carries when the gateway cannot be reached. */
+export declare const GATEWAY_UNAVAILABLE = "gateway_unavailable";
+/** The reason a fail-closed verdict carries when the gateway is reachable but the screening
+ *  deadline was exceeded — a timeout is a verdict, not a hang (INV-6 / FEED-001 AC-005). */
+export declare const GOVERNANCE_TIMEOUT = "governance_timeout";
+/**
+ * Build the fail-closed verdict (SI-001 / DB-001 / INV-6): never deliver/send ungated content, never
+ * hang. `reason` distinguishes "could not connect" (`gateway_unavailable`) from "connected but the
+ * screening deadline elapsed" (`governance_timeout`).
+ */
+export declare function failClosedVerdict(direction: ScreenDirection, reason?: string): ScreenVerdict;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,qEAAqE;AACrE,MAAM,MAAM,eAAe,GAAG,UAAU,GAAG,SAAS,CAAC;AAErD;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,iBAAiB,GAAG,OAAO,GAAG,OAAO,GAAG,QAAQ,GAAG,MAAM,CAAC;AAEtE,yGAAyG;AACzG,MAAM,MAAM,qBAAqB,GAAG,SAAS,GAAG,QAAQ,GAAG,OAAO,GAAG,MAAM,CAAC;AAE5E;;;;;;;;GAQG;AACH,MAAM,MAAM,kBAAkB,GAAG,QAAQ,GAAG,YAAY,GAAG,cAAc,CAAC;AAE1E;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,qBAAqB,CAAC;IACnC,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,kFAAkF;IAClF,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,kGAAkG;AAClG,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,eAAe,CAAC;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,gGAAgG;IAChG,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;;;OAMG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC;CAC1D;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,aAAa;IAC5B,WAAW,EAAE,iBAAiB,CAAC;IAC/B,OAAO,CAAC,EAAE,UAAU,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,2FAA2F;IAC3F,MAAM,CAAC,EAAE,eAAe,EAAE,CAAC;IAC3B;;;;;;;;OAQG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,qBAAqB;IACpC,cAAc,CAAC,OAAO,EAAE,UAAU,EAAE,GAAG,EAAE,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;IAChF,aAAa,CAAC,OAAO,EAAE,UAAU,EAAE,GAAG,EAAE,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;CAChF;AAED,wFAAwF;AACxF,eAAO,MAAM,mBAAmB,wBAAwB,CAAC;AACzD;4FAC4F;AAC5F,eAAO,MAAM,kBAAkB,uBAAuB,CAAC;AAEvD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,eAAe,EAAE,MAAM,GAAE,MAA4B,GAAG,aAAa,CAcjH"}

package/dist/types.js

@@ -0,0 +1,39 @@
+/**
+ * @cello-protocol/gateway — the security gateway contract.
+ *
+ * The gateway is a SEPARATE program from the daemon (M9-CORE-001 / V3 split-deployment).
+ * The daemon holds ONLY this interface and its two call sites; all detection lives in the
+ * gateway program. The same interface backs both the local sidecar (Phase 1) and the
+ * remote mTLS gateway (Phase 2) — Phase 2 is a transport swap behind `SecurityGatewayClient`,
+ * not a rewrite.
+ *
+ * M9-CORE-001 implements the seam with a pass-through: every message is screened (the call
+ * happens at the two fixed points) but the verdict is always `allow`, except the fail-closed
+ * `block` a configured-but-unreachable gateway returns. Detectors and the redact/warn
+ * dispositions arrive in later stories (M9-IN-*, M9-OUT-*, M9-FEED-001).
+ */
+/** The reason code a fail-closed verdict carries when the gateway cannot be reached. */
+export const GATEWAY_UNAVAILABLE = "gateway_unavailable";
+/** The reason a fail-closed verdict carries when the gateway is reachable but the screening
+ *  deadline was exceeded — a timeout is a verdict, not a hang (INV-6 / FEED-001 AC-005). */
+export const GOVERNANCE_TIMEOUT = "governance_timeout";
+/**
+ * Build the fail-closed verdict (SI-001 / DB-001 / INV-6): never deliver/send ungated content, never
+ * hang. `reason` distinguishes "could not connect" (`gateway_unavailable`) from "connected but the
+ * screening deadline elapsed" (`governance_timeout`).
+ */
+export function failClosedVerdict(direction, reason = GATEWAY_UNAVAILABLE) {
+    const cause = reason === GOVERNANCE_TIMEOUT
+        ? "the security gateway did not return a verdict within the screening deadline"
+        : "the security gateway could not be reached";
+    return {
+        disposition: "block",
+        reason,
+        guidance: direction === "outbound"
+            ? `Fail-closed: ${cause}, so this message was NOT sent. Nothing left the machine. ` +
+                "Check that the gateway sidecar is running, then retry."
+            : `Fail-closed: ${cause}, so inbound content was not delivered to the agent. It was left ` +
+                "unacknowledged, so the sender redelivers it on a later attempt — screened once the gateway responds.",
+    };
+}
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAyGH,wFAAwF;AACxF,MAAM,CAAC,MAAM,mBAAmB,GAAG,qBAAqB,CAAC;AACzD;4FAC4F;AAC5F,MAAM,CAAC,MAAM,kBAAkB,GAAG,oBAAoB,CAAC;AAEvD;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAAC,SAA0B,EAAE,SAAiB,mBAAmB;IAChG,MAAM,KAAK,GAAG,MAAM,KAAK,kBAAkB;QACzC,CAAC,CAAC,6EAA6E;QAC/E,CAAC,CAAC,2CAA2C,CAAC;IAChD,OAAO;QACL,WAAW,EAAE,OAAO;QACpB,MAAM;QACN,QAAQ,EACN,SAAS,KAAK,UAAU;YACtB,CAAC,CAAC,gBAAgB,KAAK,4DAA4D;gBACjF,wDAAwD;YAC1D,CAAC,CAAC,gBAAgB,KAAK,mEAAmE;gBACxF,sGAAsG;KAC7G,CAAC;AACJ,CAAC"}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@cello-protocol/gateway",
+  "version": "0.0.1",
+  "private": false,
+  "type": "module",
+  "engines": {
+    "node": ">=24"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "cello-gateway": "./dist/bin/cello-gateway.js"
+  },
+  "files": [
+    "dist/",
+    "package.json"
+  ],
+  "dependencies": {
+    "re2-wasm": "^1.0.2"
+  },
+  "optionalDependencies": {
+    "re2": "^1.25.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.6.2",
+    "tsx": "^4.22.4"
+  },
+  "scripts": {
+    "typecheck": "tsc --build",
+    "test": "vitest run"
+  }
+}