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 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. 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 (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

npm install invinoveritas-governance-gate-core

Usage

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

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