Repository avatar
AI Tools
v0.3.4
active

vizier-guard

io.github.vassiliylakhonin/vizier-guard

Deterministic authorization and security guard for AI agent actions with signed receipts.

Documentation

Vizier

Authorize AI agent actions before tools execute.

npm CI Release License: MIT

Vizier checks proposed tool calls against owner-signed, scoped, expiring permissions and deterministic policies. It returns ALLOW, BLOCK, or REVIEW, with rule results and a receipt bound to the request. Your trusted guard enforces the result before a deployment, repository write, database change, message, or payment API call.

Use the TypeScript or Python client, protect existing tools with the MCP proxy, or integrate through REST and A2A. No LLM is involved in the authorization decision.

Try the playground · Quick start · SDK example · MCP · API reference · Threat model

What can you control?

WorkflowWhat the integration can enforceStart here
Agent tool callsPermitted actions, exact targets, constraints, and grant expirySigned delegation
Existing MCP toolsAllowed tools and upstream routes, checked before forwardingMCP enforcement proxy
Cloudflare Worker deploymentsOne existing Worker and human approval of the exact uploaded versionLocal preparation demo
Sensitive operationsAn explicit human-review step bound to the proposed actionReview helpers

An API key identifies the integration. A signed grant carries the owner's permission. Keep the private signing key and protected tool credentials outside the agent's control.

Quick start

Try the browser playground, or run the reproducible first-BLOCK walkthrough. It starts a disposable local Worker, sends the same request through the TypeScript and Python clients, and proves that both clients reject a tampered receipt. No account, production API key, Cloudflare account, deployment, or payment is needed.

From a source checkout, with Node.js 24+ and Python 3.9+:

npm ci
python3 -m venv .venv
.venv/bin/python -m pip install -e 'packages/python-sdk[receipts]'
VIZIER_DEMO_PYTHON="$PWD/.venv/bin/python" npm run demo:first-block -- --signed

Expected: BLOCK (GRANT_REQUIRED) in both languages, verified request hashes and ES256 signatures, followed by rejection of tampered receipts. This checks current source. The published-package path runs the same signed checks against the released clients, npm 0.5.17 and PyPI vizier-guard 0.3.4.

Optional: prepare a deployment review

To prepare a deployment review locally with Node.js 24+:

mkdir vizier-demo
cd vizier-demo
npm install @agenda-intelligence/vizier-sdk@0.5.17 @agenda-intelligence/vizier-gated-deploy@0.5.17
npx --no-install vizier-worker-deploy prepare \
  --scope node_modules/@agenda-intelligence/vizier-gated-deploy/examples/scope.json \
  --plan node_modules/@agenda-intelligence/vizier-gated-deploy/examples/plan.json

No API key or Cloudflare account is needed for prepare. After installation, this step runs locally without network calls. The bundled scope and plan use synthetic IDs.

You get JSON containing:

  • review: the exact Worker version and traffic percentage to review;
  • review_hash: a SHA-256 hash binding that review to its contents;
  • authority: the action and target scope the owner would need to sign.

This prepares a review; it does not authorize or deploy anything. For a real sandbox, follow the operator setup and recovery guide. The adapter's submit and execute modes require additional credentials; execution requires both a matching signed grant and approval of the exact review.

For general policy exploration, use the local REST scenarios. Anonymous evaluation can return BLOCK or REVIEW, never ALLOW.

How it works

flowchart LR
    Owner[Owner-controlled signer] -->|Scoped, expiring grant| Guard[Trusted tool guard]
    Agent[Agent proposes action] --> Guard
    Guard -->|Exact action + grant| Vizier[Vizier policy service]
    Vizier -->|Decision + request-bound receipt| Guard
    Guard -->|Validated ALLOW| Tool[Protected tool]
    Guard -->|Explicit review submission| Human[Human review workflow]
  1. The owner signs an ES256 delegation for a principal, agent, permitted actions, constraints, and expiry.
  2. The guard submits the intended action and grant to /v1/verify.
  3. Vizier checks the signature, identities, expiry, exact authority binding, and deterministic policies.
  4. The guard validates the response and request binding before invoking the protected tool.
DecisionWhat the caller should do
ALLOWProceed only through the trusted executor, with the exact authorized action and required execution controls.
BLOCKStop. Inspect reason_codes and policy_results; fix the underlying request or permissions.
REVIEWStop execution. Submit a separate human review explicitly if the integration supports it.

A verification response does not execute the action or automatically open a review.

Start with signed delegation

Prerequisites: an operator-issued API key, a registered principal public key, and a matching owner-issued grant. Follow delegation setup first. An API key alone is insufficient in required-grant mode.

Install the TypeScript client (Node.js 24+):

npm install @agenda-intelligence/vizier-sdk@0.5.17

Supply VIZIER_API_KEY and VIZIER_GRANT_FILE to the trusted guard. For this example, the grant must bind platform-owner to release-agent and contain exactly the authority object below. Keep the private signer separate.

Save as authorize.mjs:

import { readFile } from "node:fs/promises";
import { Vizier } from "@agenda-intelligence/vizier-sdk";

const apiKey = process.env.VIZIER_API_KEY;
const grantPath = process.env.VIZIER_GRANT_FILE;
if (!apiKey || !grantPath) {
  throw new Error("Set VIZIER_API_KEY and VIZIER_GRANT_FILE in the trusted guard.");
}

const vizier = new Vizier({
  baseUrl: "https://vizier.agendamcp.dpdns.org",
  apiKey,
});
const grant = (await readFile(grantPath, "utf8")).trim();

const result = await vizier.authorize({
  agent: { id: "release-agent", owner: "platform-owner" },
  principal: { id: "platform-owner" },
  action: {
    type: "deploy_worker",
    target: "worker:example-worker",
    parameters: { commit: "reviewed-commit" },
  },
  authority: {
    allowed_actions: ["deploy_worker"],
    constraints: {
      allowed_targets: ["worker:example-worker"],
      allowed_sensitive_actions: ["deploy_worker"],
    },
  },
  context: { request_id: null, timestamp: null, source: "rest" },
  grant,
});

// authorize() throws unless the response establishes a request-bound ALLOW
// with matching, unexpired principal-signed delegation.
console.log("Authorized request:", result.receipt.id);

Run node authorize.mjs after configuring those prerequisites. A valid authorization prints a receipt ID; a refusal throws. This example performs only the authorization request. Use the deployment adapter for the separate, version-specific execution workflow.

authorize() validates the response contract, recomputes the request hash, and rejects BLOCK, REVIEW, expired grants, and mismatched delegation. It relies on the configured trusted service and HTTPS: the unsigned receipt object is not itself a signature. When the Worker has a receipt signing key and the request sends X-Vizier-Receipt: jws, enforcement responses also carry receipt_jws (ES256, verifiable against /.well-known/jwks.json). The published clients, npm 0.5.17 and PyPI vizier-guard 0.3.4, verify it against the JWKS when present; absence is tolerated by default, and opt-in requireReceiptJws (TypeScript) or require_receipt_jws=True (Python) makes a missing JWS an error. See the versioned walkthrough. Execution, request immutability, idempotency, and replay controls remain the integration's responsibility.

Connect through MCP

Call the hosted verification service

For a Streamable HTTP MCP client:

https://vizier.agendamcp.dpdns.org/mcp

Discovery needs no API key. Read the discovered tool schema and metadata before constructing a request. Anonymous verification is evaluation-only and cannot return ALLOW.

From a source checkout, inspect either supported connection profile with Node 24+ and no extra dependencies:

node examples/mcp-connect.ts --profile session
node examples/mcp-connect.ts --profile stateless

These commands perform read-only discovery. A rejected connection includes correction guidance; fix the request and explicitly retry the selected profile.

Configuration for a stdio-only MCP client

This pinned transport adapter connects to the hosted verification service anonymously:

{
  "mcpServers": {
    "vizier": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote@0.15.1",
        "https://vizier.agendamcp.dpdns.org/mcp",
        "--transport", "http-only"
      ]
    }
  }
}

It exposes evaluation, not permission to execute: anonymous calls can return BLOCK or REVIEW, never ALLOW.

Enforce authorization on your own MCP tools

The private MCP enforcement proxy sits between the agent and a supported HTTP MCP server. It filters tool discovery and checks configured calls before forwarding them. Configure the signed grant, allowed tools, upstream identity, and protected credentials using the proxy setup guide.

The hosted verification service does not intercept your other tools automatically. Remove the agent's direct upstream access so it cannot bypass the proxy.

Trust boundaries

  • Authorization scope: Vizier checks permissions and policy rules. It does not establish factual truth, legal clearance, payment settlement, or successful tool execution.
  • Receipts: /v1/verify receipts bind a decision to a request hash. The receipt object is unsigned; when a receipt signing key is configured and the caller sends X-Vizier-Receipt: jws, enforcement responses (not anonymous evaluation) add receipt_jws, a compact ES256 JWS over that exact receipt, verifiable with the published JWKS. The delegation grant is owner-signed. Action Covenants have separate signed formats and compatibility limits.
  • Execution: a guard protects only the path it controls. An agent or operator with direct tool credentials can bypass it. Grants are reusable until they expire unless the principal signs single_use: true; a single-use grant is spent at ALLOW, not when the action succeeds, enforcement of one fails closed (BLOCK) without the D1 binding, and revocation is operator-driven (see delegation grants).
  • Deployment review: claiming an approval and performing a cloud deployment are not atomic. Reconcile uncertain outcomes before retrying; see recovery guidance.
  • Self-hosting: optional grant mode permits caller-asserted authority. Those receipts do not establish owner delegation; choose the intended mode explicitly.

See the threat model and security review before relying on an integration boundary.

Status and evidence

Experimental. The npm examples above pin version 0.5.17. Evaluate the integration in your own sandbox before using it for consequential actions.

The maintainer's Worker deployment demo records eight scenarios, including changed versions, out-of-scope targets, expired grants, missing approval, and replay. The report includes a sanitized trace and explains its limitations. It is owner-run testing, not independent customer adoption.

Authorization requirements coverage

A 2026 review of authorization architectures for tool-using agents (arXiv:2609.15906, 89 sources) defines seven structural requirements for agent authorization. Where Vizier stands against them, mapped to code:

RequirementStatusWhat Vizier doesWhat it does not do
R1 AttributabilityPartialEvery receipt records authority_provenance (principal_signed, trusted_integration, or unverified, which cannot produce ALLOW) and, for signed grants, the verified jti, issuer, subject, key id, and expiry.Reconstruct a multi-hop principal chain across organizations; the immediate grant is the whole chain.
R2 Explicit delegationCovered (single hop)Owner-signed ES256 grants bind this agent, these action types, these constraint values, and an expiry, verified offline against operator-registered keys; a caller-asserted API key is never enough in required-grant mode.Evaluate natural-language task scope; constraints are structured values only.
R3 Monotonic attenuationNot doneGrants are single-hop; nothing is delegated onward, so there is no chain to attenuate.Chained delegation with enforced scope narrowing, and provenance of arguments drawn from untrusted content (the direction of e.g. arXiv:2611.00729).
R4 Aggregation boundsPartial (first step)Per-principal aggregate bounds over a fixed window: a usage constraint in a principal-signed grant caps the number of calls and/or the cumulative admitted amount per window, counted in D1 (migration 0017), enforced in the same deterministic evaluation and claimed atomically after ALLOW, failing closed without the ledger. See usage limits. The review identifies this requirement as the least satisfied across the field, not just here.Bound cumulative information use against the original task scope: counters measure how many calls and how much money, not what the calls read, returned, or caused. Windows are fixed, not sliding, so use resets at each boundary.
R5 Temporal validityPartialGrant expiry is enforced (60s skew), revocation by jti via POST /v1/grants/revoke (D1) or the VIZIER_REVOKED_GRANTS secret, and single-use grants are spent at ALLOW, failing closed without the D1 binding.Task-lifecycle revalidation: an unexpired grant stays valid if the workflow around it changes. Revocation is operator-driven, not principal-signed.
R6 Runtime enforcementCovered for guarded pathsDeterministic policy evaluation at the invocation layer (REST, MCP, A2A, and the MCP proxy) with no LLM in the decision; evaluation mode cannot return ALLOW.Cover paths that bypass the guard: a caller holding direct tool credentials never traverses Vizier (see Trust boundaries).
R7 Tamper-resistant, attributable auditPartialMetadata-only D1 audit log (no caller payloads), opt-in receipt_jws verifiable against the published JWKS, and hash-chained stored receipts: each row's receipt_hash covers its own metadata and the previous row's hash (migration 0012), re-verified end to end by GET /v1/audit/chain. The chain head is anchored outside the audited database every 6 hours: a GitHub Actions workflow commits the public GET /v1/audit/chain/head response to the public audit-anchors branch, so a silent deletion of the newest rows becomes detectable once the next anchor lands. See external anchors.Writers append with a compare-and-set on the chain head and retry on conflict, so concurrent writes do not fork it; if every retry loses, that receipt is not stored. Retention pruning records an anchor hash (migration 0014) that anyone with D1 write access can edit. Rows written before migration 0012 are unchained. Anchors are periodic, so receipts newer than the last anchor are uncovered, and the anchor branch lives in this repository, so a repository admin can still rewrite it (a visible force-push, not a silent edit). No cross-organization audit correlation.

Statuses describe this repository's code and tests; live deployment state must be checked against the deployed service.

Documentation and packages

NeedReference
Authorization and owner keysQuickstart · Delegation grants
JavaScript / TypeScriptSDK · npm
PythonPython SDK, function guards, and adapters
MCP toolsEnforcement proxy
Infrastructure deploymentAdapter · Operator guide
Human approval by emailVizier + OAE worked example
Anonymous pathPublic evidence
REST and A2AAPI reference · OpenAPI · Agent card
Usage measurement and privacyData collected, retention, and report access
Cumulative limits and audit integrityBudget ceiling · Per-window usage bounds · External audit anchors
Architecture and scopeArchitecture · Claim ledger · Pilot scope

Development and contributions

Requires Node.js 24+:

git clone https://github.com/vassiliylakhonin/vizier.git
cd vizier
npm ci
npm run check

check runs package builds, type checks, migration checks, lint, tests, and a Worker deployment dry run. It does not publish or deploy. Python SDK checks run separately with python -m pytest packages/python-sdk after installing pytest.

For bugs or integration questions, open an issue. Include a sanitized request, SDK version, expected decision, and actual result. Never include API keys, private keys, grants, or approval tokens. Reproducible policy cases, adapter examples, and documentation fixes are useful contributions.

License

MIT License.

Session guards and policy probes (source checkout)

The Node MCP proxy has a default third-consecutive-call loop block, optional operator-owned path/URL argument rules, and a labelled private-source to external-sink session guard. vizier test-policy reports synthetic bypasses and controls using that same argument evaluator. See SESSION_GUARD.md for setup, source-checkout commands, and limits, especially remote filesystems, symlink races, restarts and unlabelled tools. This is not complete prompt-injection protection.