invinoveritas-governance-gate-core 0.1.0

package/README.md

@@ -0,0 +1,98 @@
+# invinoveritas-governance-gate-core
+
+The framework-agnostic core for an **independent pre-execution governance gate**.
+
+An agent can self-serve memory, tools, reasoning, even a wallet. The one thing it cannot self-serve
+is an **independent second opinion on its own proposed action** — you can't self-issue a verdict that
+a third party trusts. This core calls invinoveritas [`/review`](https://api.babyblueviper.com) for
+that verdict and returns a normalized gate decision plus a **portable, recomputable proof**: a
+BIP-340-signed Nostr event, Bitcoin-anchored on the public [`/ledger`](https://api.babyblueviper.com/ledger).
+Anyone can re-verify the proof offline via `/verify-proof` **without trusting the presenter or us.**
+
+This is the shared primitive. Thin per-surface adapters wrap it — see
+[`invinoveritas-metamask-snap`](../metamask-snap) (verdict before you sign a transaction), and the
+LangGraph / OpenAI-Agents / GOAT patterns.
+
+## Why this and not a self-signed receipt
+
+Most "action receipt" schemes sign the record with **the agent's own key** — that proves *the agent
+says it did X*, not *an independent party judged X sound before it ran*. And a signed hash-chain
+proves internal ordering but can be regenerated wholesale. This gate is built around the two things a
+self-signed receipt structurally lacks:
+
+1. **Independence** — the verdict comes from a party that isn't the actor.
+2. **External time anchor** — every verdict is Bitcoin-anchored (OpenTimestamps), so "judged before
+   the outcome" is checkable against a clock the operator doesn't control. Omission becomes as
+   legible as publication.
+
+## Install
+
+```bash
+npm install invinoveritas-governance-gate-core
+```
+
+## Usage
+
+```ts
+import { reviewAction } from "invinoveritas-governance-gate-core";
+
+const result = await reviewAction(
+  {
+    artifact: JSON.stringify({ tool: "transfer", to: "0xabc…", amount: "1000 USDC" }),
+    artifactType: "onchain_action", // or "trade", "tool_call", "general"
+    context: "Agent is about to move treasury funds.",
+  },
+  {
+    apiKey: process.env.INVINOVERITAS_API_KEY, // free: POST /register {"label":"your-app"}
+    failMode: "closed", // irreversible action -> BLOCK if the gate is unavailable
+    sign: true,         // attach the recomputable proof (default)
+  },
+);
+
+// result.decision : "ALLOW" | "BLOCK" | "ESCALATE"
+// result.verdict  : "approve" | "approve_with_concerns" | "reject" | "review_unavailable"
+// result.proof    : portable signed proof — hand it downstream
+// result.recomputeProofAt : where anyone re-verifies it (free, no auth)
+
+if (result.decision === "BLOCK") {
+  // hold the action; surface result.summary / result.issues
+}
+```
+
+### Fail mode is explicit, per surface
+
+The gate is **advisory by default** (`failMode: "open"`) — a slow or erroring gate never blocks the
+host. For **irreversible / side-effecting** actions, set `failMode: "closed"` so gate-unavailability
+blocks instead of silently passing, or `"escalate"` to route to a human/confirmation path. This is the
+property a pure observability hook lacks: it can be made *authority*, not just a log.
+
+### Receiving half of the handshake
+
+```ts
+import { verifyProof } from "invinoveritas-governance-gate-core";
+
+// A proof another agent handed you — verify it without trusting them OR us.
+const v = await verifyProof({ event: someProof.proof_payload });
+// v.valid === true  =>  the verdict is authentic and unmodified
+```
+
+## API
+
+- `reviewAction(action, config) => Promise<GateResult>` — never throws; failures resolve per `failMode`.
+- `verifyProof({ event | proofId }, config) => Promise<{ valid }>` — free, no auth.
+
+| `GovernanceGateConfig` | default | |
+|---|---|---|
+| `apiKey` | — | Bearer key (free via `/register`). Omitted ⇒ unfunded ⇒ `failMode` applies. |
+| `baseUrl` | `https://api.babyblueviper.com` | |
+| `timeoutMs` | `5000` | a gate must never hang the host |
+| `failMode` | `"open"` | `"open"` ALLOW / `"closed"` BLOCK / `"escalate"` ESCALATE on gate-unavailable |
+| `sign` | `true` | attach the recomputable proof |
+
+`ProposedAction.stateHash` (optional): SHA-256 hex of the caller's state at request time — binds the
+proof to both the action AND the state, so a verifier confirms the decision was made against the exact
+state the caller had.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,92 @@
+/**
+ * invinoveritas-governance-gate-core
+ *
+ * Framework-agnostic core for an INDEPENDENT pre-execution governance gate.
+ *
+ * The one thing an agent (or a wallet, or a middleware) cannot self-serve is an independent
+ * second opinion on its own proposed action — you can't self-issue a verdict that a third party
+ * trusts. This core calls invinoveritas `/review` for that verdict and returns a normalized
+ * gate decision plus a PORTABLE, RECOMPUTABLE proof (a BIP-340-signed Nostr event, Bitcoin-anchored
+ * on the public /ledger). Any party can re-verify the proof offline via `/verify-proof` without
+ * trusting the presenter OR us.
+ *
+ * Design invariants:
+ *  - Advisory by default (failMode="open"): a slow/erroring gate NEVER blocks execution.
+ *  - But fail mode is EXPLICIT and per-surface: side-effecting / irreversible surfaces should set
+ *    failMode="closed" so gate-unavailability blocks rather than silently passing.
+ *  - The verdict is from a party that ISN'T the actor (independence). The proof carries its own
+ *    pubkey + verify URL (self-describing); checking it needs nothing out-of-band.
+ *
+ * This is the shared primitive; thin per-surface adapters (MetaMask Snap, LangGraph ToolNode,
+ * OpenAI Agents on_tool_start, etc.) wrap it. See integrations/metamask-snap for the first adapter.
+ */
+export type Verdict = "approve" | "approve_with_concerns" | "reject" | "review_unavailable";
+/** What the host should do with the action. */
+export type GateDecision = "ALLOW" | "BLOCK" | "ESCALATE";
+/**
+ * Behavior when the gate itself is unavailable (timeout, error, 402-unfunded, malformed response).
+ *  - "open":   ALLOW (advisory — the default; the gate is a second opinion, not a blocker)
+ *  - "closed": BLOCK (fail-safe — for irreversible / side-effecting surfaces)
+ *  - "escalate": ESCALATE (hand to a human / confirmation path)
+ */
+export type FailMode = "open" | "closed" | "escalate";
+export interface GovernanceGateConfig {
+    /** Bearer API key. Get one free: POST {baseUrl}/register {"label":"your-app"}. Omitted => unfunded => failMode applies. */
+    apiKey?: string;
+    /** API base. Default https://api.babyblueviper.com */
+    baseUrl?: string;
+    /** Per-call timeout. Default 5000ms — a gate must never hang the host. */
+    timeoutMs?: number;
+    /** What to do when the gate is unavailable. Default "open" (advisory). Set "closed" for irreversible actions. */
+    failMode?: FailMode;
+    /** Attach a portable recomputable proof to the verdict. Default true (the whole point — trust the math). */
+    sign?: boolean;
+}
+export interface ProposedAction {
+    /** The thing to judge: a decoded tx, a tool call, a trade, a plan. For onchain_action, a human/JSON description of the tx. */
+    artifact: string;
+    /** Tailors the review. Use "onchain_action" for a prepared tx (scam/drainer/approval/poisoning checks), "trade", "tool_call", etc. */
+    artifactType?: string;
+    /** What this is trying to do / why now — helps the verdict judge intent vs. action. */
+    context?: string;
+    /**
+     * Optional SHA-256 hex of the caller's state at request time. When set, the signed proof binds to
+     * BOTH the action AND the state — so a verifier confirms the decision was made against the exact
+     * state the caller had, not just the action proposed. Changing state after invalidates the proof.
+     */
+    stateHash?: string;
+}
+export interface GateResult {
+    /** Normalized host action. */
+    decision: GateDecision;
+    /** Raw verdict from the independent reviewer. */
+    verdict: Verdict;
+    confidence?: number;
+    summary?: string;
+    issues?: unknown[];
+    /** Deterministic on-chain risk findings (decode-the-calldata-yourself), present for onchain_action. */
+    onchainRisk?: unknown;
+    /** Portable signed proof — hand it downstream; anyone re-verifies it via recomputeProofAt. */
+    proof?: unknown;
+    /** Where to recompute/verify the proof (free, no auth). */
+    recomputeProofAt?: string;
+    /** Human-readable note when the gate was unavailable. */
+    reason?: string;
+}
+/**
+ * Get an independent, recomputable verdict on a proposed action before it executes.
+ * Never throws — on any failure it returns a `review_unavailable` result resolved per `failMode`.
+ */
+export declare function reviewAction(action: ProposedAction, config?: GovernanceGateConfig): Promise<GateResult>;
+/**
+ * Verify a signed invinoveritas proof someone handed you — the receiving half of the handshake.
+ * FREE, no auth. Recomputes the Nostr event id + checks the BIP-340 signature against the published
+ * key, so you trust neither the presenter nor us. Pass the signed `event` object or a `proofId`.
+ */
+export declare function verifyProof(input: {
+    event?: Record<string, unknown>;
+    proofId?: string;
+}, config?: GovernanceGateConfig): Promise<{
+    valid: boolean;
+    [k: string]: unknown;
+}>;

package/dist/index.js

@@ -0,0 +1,132 @@
+/**
+ * invinoveritas-governance-gate-core
+ *
+ * Framework-agnostic core for an INDEPENDENT pre-execution governance gate.
+ *
+ * The one thing an agent (or a wallet, or a middleware) cannot self-serve is an independent
+ * second opinion on its own proposed action — you can't self-issue a verdict that a third party
+ * trusts. This core calls invinoveritas `/review` for that verdict and returns a normalized
+ * gate decision plus a PORTABLE, RECOMPUTABLE proof (a BIP-340-signed Nostr event, Bitcoin-anchored
+ * on the public /ledger). Any party can re-verify the proof offline via `/verify-proof` without
+ * trusting the presenter OR us.
+ *
+ * Design invariants:
+ *  - Advisory by default (failMode="open"): a slow/erroring gate NEVER blocks execution.
+ *  - But fail mode is EXPLICIT and per-surface: side-effecting / irreversible surfaces should set
+ *    failMode="closed" so gate-unavailability blocks rather than silently passing.
+ *  - The verdict is from a party that ISN'T the actor (independence). The proof carries its own
+ *    pubkey + verify URL (self-describing); checking it needs nothing out-of-band.
+ *
+ * This is the shared primitive; thin per-surface adapters (MetaMask Snap, LangGraph ToolNode,
+ * OpenAI Agents on_tool_start, etc.) wrap it. See integrations/metamask-snap for the first adapter.
+ */
+const DEFAULT_BASE_URL = "https://api.babyblueviper.com";
+const DEFAULT_TIMEOUT_MS = 5000;
+function verdictToDecision(verdict, failMode) {
+    switch (verdict) {
+        case "reject":
+            return "BLOCK";
+        case "approve_with_concerns":
+            return "ESCALATE";
+        case "approve":
+            return "ALLOW";
+        case "review_unavailable":
+        default:
+            return failMode === "closed" ? "BLOCK" : failMode === "escalate" ? "ESCALATE" : "ALLOW";
+    }
+}
+async function postJson(url, body, opts) {
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), opts.timeoutMs);
+    try {
+        const headers = { "Content-Type": "application/json" };
+        if (opts.apiKey)
+            headers["Authorization"] = `Bearer ${opts.apiKey}`;
+        const res = await fetch(url, {
+            method: "POST",
+            headers,
+            body: JSON.stringify(body),
+            signal: ctrl.signal,
+        });
+        let data = null;
+        try {
+            data = await res.json();
+        }
+        catch {
+            data = null;
+        }
+        return { ok: res.ok, status: res.status, data };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * Get an independent, recomputable verdict on a proposed action before it executes.
+ * Never throws — on any failure it returns a `review_unavailable` result resolved per `failMode`.
+ */
+export async function reviewAction(action, config = {}) {
+    const baseUrl = (config.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+    const failMode = config.failMode ?? "open";
+    const timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const sign = config.sign ?? true;
+    const unavailable = (reason) => ({
+        decision: verdictToDecision("review_unavailable", failMode),
+        verdict: "review_unavailable",
+        reason,
+    });
+    if (!config.apiKey) {
+        return unavailable(`No invinoveritas API key. Get one free: POST ${baseUrl}/register {"label":"your-app"}. ` +
+            `Gate resolved by failMode="${failMode}".`);
+    }
+    try {
+        const { ok, status, data } = await postJson(`${baseUrl}/review`, {
+            artifact: action.artifact,
+            artifact_type: action.artifactType ?? "general",
+            context: action.context,
+            state_hash: action.stateHash,
+            sign,
+        }, { apiKey: config.apiKey, timeoutMs });
+        if (status === 402) {
+            return unavailable(`Gate skipped — unfunded key (HTTP 402). Resolved by failMode="${failMode}".`);
+        }
+        if (!ok || !data || typeof data.verdict !== "string") {
+            return unavailable(`Review unavailable (HTTP ${status}). Resolved by failMode="${failMode}".`);
+        }
+        const verdict = data.verdict;
+        return {
+            decision: verdictToDecision(verdict, failMode),
+            verdict,
+            confidence: data.confidence,
+            summary: data.summary,
+            issues: data.issues ?? [],
+            onchainRisk: data.onchain_risk,
+            proof: data.proof,
+            recomputeProofAt: data.proof ? `${baseUrl}/verify-proof` : undefined,
+        };
+    }
+    catch {
+        return unavailable(`Review timed out or errored. Resolved by failMode="${failMode}".`);
+    }
+}
+/**
+ * Verify a signed invinoveritas proof someone handed you — the receiving half of the handshake.
+ * FREE, no auth. Recomputes the Nostr event id + checks the BIP-340 signature against the published
+ * key, so you trust neither the presenter nor us. Pass the signed `event` object or a `proofId`.
+ */
+export async function verifyProof(input, config = {}) {
+    const baseUrl = (config.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+    const timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    if (!input.event && !input.proofId) {
+        return { valid: false, error: "Provide `event` (the signed proof object) or `proofId`." };
+    }
+    try {
+        const { ok, status, data } = await postJson(`${baseUrl}/verify-proof`, { event: input.event, proof_id: input.proofId }, { timeoutMs });
+        if (!ok || !data)
+            return { valid: false, error: `verify-proof unavailable (HTTP ${status})` };
+        return data;
+    }
+    catch {
+        return { valid: false, error: "verify-proof timed out or errored." };
+    }
+}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "invinoveritas-governance-gate-core",
+  "version": "0.1.0",
+  "description": "Framework-agnostic core for an independent pre-execution governance gate — calls invinoveritas /review for a verdict an agent can't self-issue, and returns a portable, recomputable, Bitcoin-anchored proof anyone can re-verify offline. Advisory by default; explicit fail-mode per surface. Thin adapters (MetaMask Snap, LangGraph, OpenAI Agents) wrap it.",
+  "keywords": [
+    "ai-agent",
+    "governance",
+    "verification",
+    "pre-execution",
+    "tool-call",
+    "onchain",
+    "guardrail",
+    "recomputable-proof",
+    "independent-verifier",
+    "second-opinion",
+    "x402"
+  ],
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "npm run build && node --test test/*.test.mjs",
+    "prepublishOnly": "npm run build"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "typescript": "^5.4.0"
+  },
+  "homepage": "https://api.babyblueviper.com",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/babyblueviper1/invinoveritas-integrations"
+  }
+}