@odingard/guardian-sdk 0.1.0 → 0.2.0

package/README.md

@@ -1,11 +1,22 @@
+<p align="center">
+  <img src=".github/assets/guardian-logo.png" alt="Guardian — human authority for AI" width="640" />
+</p>
+
 # @odingard/guardian-sdk
 
-Guardian agent SDK — let an AI agent request governed capabilities and execute
-consequential actions under human authority. The agent proposes; the human
-decides. Every decision is deterministic (`ALLOW` / `ASK` / `DENY`) and every
+[![npm version](https://img.shields.io/npm/v/@odingard/guardian-sdk)](https://www.npmjs.com/package/@odingard/guardian-sdk)
+[![npm downloads](https://img.shields.io/npm/dm/@odingard/guardian-sdk)](https://www.npmjs.com/package/@odingard/guardian-sdk)
+[![MCP registry](https://img.shields.io/badge/MCP_registry-guardian--mcp-blue)](https://registry.modelcontextprotocol.io/)
+[![Guardian MCP server on mcprush](https://mcprush.com/badge/odingard-guardian-mcp/card.svg)](https://mcprush.com/to/odingard-guardian-mcp?ref=badge)
+[![License](https://img.shields.io/badge/license-Apache--2.0-blue)](LICENSE)
+
+**Human Authority Infrastructure for Autonomous AI.** The agent proposes; the human
+decides. This SDK lets an AI agent request governed capabilities and execute
+consequential actions under human authority. Every decision is deterministic (`ALLOW` / `ASK` / `DENY`) and every
 execution produces a tamper-evident receipt.
 
-Hosted Guardian: https://guardian.odingard.com
+Hosted Guardian: [guardian.odingard.com](https://guardian.odingard.com) — free tier for developers
+(1 agent, 1 connection, 50 protected actions/month), no card required.
 
 ## Install
 
@@ -13,15 +24,15 @@ Hosted Guardian: https://guardian.odingard.com
 npm install @odingard/guardian-sdk
 ```
 
-Requires Node.js >= 20.
+Requires Node.js >= 22 (receipt verification uses `node:crypto` Ed25519; browser runtimes are not supported in 0.2).
 
 ## Quickstart
 
 ```ts
-import { createGuardianClient } from "@odingard/guardian-sdk";
+import { classifyRequestResult, createGuardianClient } from "@odingard/guardian-sdk";
 
 const guardian = createGuardianClient({
-  baseUrl: "https://api.guardian.odingard.com",
+  baseUrl: "https://guardian-api.odingard.com",
   credential: process.env.GUARDIAN_AGENT_CREDENTIAL!, // gac1.… issued per agent
 });
 
@@ -33,19 +44,23 @@ const result = await guardian.request({
   arguments: { orderId: "ord_123" },
 });
 
-if (result.ok && result.decision === "ALLOW") {
+const d = classifyRequestResult(result); // the one fail-closed reading
+
+if (d.decision === "ALLOW") {
   // 2. Guardian minted a single-use capability. Execute it.
   const execution = await guardian.execute({
-    requestId: result.requestId,
-    capabilityToken: result.capabilityToken!,
+    requestId: d.requestId,
+    capabilityToken: d.capabilityToken,
   });
   console.log(execution.ok ? execution.receipt : execution.reasonCode);
-} else if (result.ok && result.decision === "ASK") {
-  // A human approves in the Guardian console, then:
-  const granted = await guardian.claim(result.requestId);
-  // …then execute as above once the capability arrives.
+} else if (d.decision === "ASK") {
+  // Held for a human. Keep d.requestId; after the human approves:
+  const granted = classifyRequestResult(await guardian.claim(d.requestId));
+  // …execute as above once granted.decision === "ALLOW".
 }
-// decision === "DENY" → refused before execution, with a reason code.
+// d.decision === "DENY" → refused before execution, with d.reasonCode.
+// Ambiguity (ALLOW without a token, unreachable Guardian, unknown shape)
+// is always DENY.
 ```
 
 ## What the agent can and cannot do
@@ -57,12 +72,232 @@ if (result.ok && result.decision === "ALLOW") {
 - `receipts(requestId)` returns the machine-readable proof of what happened,
   who authorized it, and what authority version applied.
 
+## Lifecycle and governed actions (0.2)
+
+| Result from `request` / `claim` | `classifyRequestResult` | What to do |
+|---|---|---|
+| `{ ok: true, decision: "ALLOW", capabilityToken }` | `ALLOW` | `execute({ requestId, capabilityToken })` |
+| `{ ok: true, decision: "ASK" }` or `{ ok: false, reasonCode: "APPROVAL_REQUIRED", requestId }` | `ASK` | keep `requestId`; `claim(requestId)` after the human decides |
+| anything else (DENY, `SERVICE_UNAVAILABLE`, ALLOW without token) | `DENY` | do not run the effect |
+
+A held ASK always carries its `requestId` (fixed in 0.2 — 0.1 dropped it).
+
+Invocation types: `tool.invoke`, `mcp.install`, `mcp.enable` (typed), and the
+governed pass-through actions `api.request`, `protected_data.derive|transform|export`,
+`agent.message`, `agent.share_context`, `agent.share_memory`,
+`agent.transfer_task`, `agent.transfer_capability` (you supply
+`materialParameters`; Guardian validates them). Optional provenance:
+`purpose`, `intentId`, `planId`, `parentActionId`, `sourceEffectId`. The wire
+schemas are exported from `@odingard/guardian-sdk/contracts`, synced from
+Guardian's canonical contracts.
+
+## Portable receipts — verify without an account
+
+```ts
+import { fetchReceiptVerificationKeys, verifyReceiptOffline, verifyReceiptOnline } from "@odingard/guardian-sdk";
+
+const { receipt } = await guardian.portableReceipt(requestId); // greceipt.v1
+const keys = await fetchReceiptVerificationKeys("https://guardian-api.odingard.com"); // public
+verifyReceiptOffline(receipt, keys.keys);
+// → { valid: true, decision: "ALLOW", effect: "verified", subject } — or { valid: false, reasonCode }
+```
+
+Offline verification checks the Ed25519 signature over the
+`guardian-canonical-json.v1` body and re-derives every embedded record against
+the receipt's evidence chain. It needs no credential, plan or Guardian service
+once you hold the keys, and is never billed. `verifyReceiptOnline` asks a
+Guardian deployment to do the same over the public `POST /v1/receipts/verify`.
+
+## Embedded approvals — humans only
+
+`createEmbeddedApprovalClient({ baseUrl, sessionToken })` lets your own UI list,
+view, approve/deny and revoke pending approvals. It requires a **human** session
+token. Agent credentials (`gak_…`, `gac1.…`) and capability tokens (`gcap.…`)
+are refused locally (`HUMAN_SESSION_REQUIRED`) before any request is sent, and
+the server independently accepts only human sessions on these routes. Agent
+credentials can never approve, create grants or revoke.
+
+## Catalog metadata (declarative)
+
+`guardianCatalog` (also `@odingard/guardian-sdk/catalog.json`) is generated from
+Guardian's canonical catalog: 62 verticals, 25 agent systems, 48 agent roles,
+221 entities, each vertical with its tier and maturity. It grants nothing:
+every action is still decided at runtime under a human's policy. Current
+honest status: 3 verticals `governed`, 58 `integration-ready` (governed
+decision path; external adapters declared, not built), 1
+`production-integrated` (recorded external-system proof). Maturity L1 = built-in
+governed, L2 = modeled/decidable, L3 = production-integrated with recorded proof.
+`verticalsForAction("tool.invoke")` lists verticals using an action.
+
+## Guardian for Steel — `@odingard/guardian-steel`
+
+Browser-agent checkout governed by Guardian: the agent can only propose
+`steel.checkout.submit`; ALLOW/ASK/DENY happens before the order; the Steel
+session and merchant credential stay on the protected executor side. See
+[`packages/steel/README.md`](packages/steel/README.md) for the boundary and
+current maturity.
+
+## Maturity of what this SDK reaches
+
+| Path | Status |
+|---|---|
+| Decision + capability + execute for `api.request`, Gmail, Calendar, tool/MCP connections | LIVE on hosted Guardian |
+| Portable receipt retrieval + offline/online verification | LIVE (staging and production publish keys) |
+| Embedded human approvals | LIVE routes; needs a human session from your Guardian sign-in |
+| Steel checkout | agent side published; protected executor proven in-process, not yet injected into hosted Guardian |
+| Framework `inProcess` mode | decision-gated only — see below |
+
+## MCP server
+
+No code needed for MCP-native agents — `@odingard/guardian-mcp` is a stdio
+MCP server exposing `guardian_invoke_tool`, `guardian_claim` and
+`guardian_receipt`. Listed on the official MCP registry as
+`io.github.Odingard/guardian-mcp` — see [mcp-server/README.md](mcp-server/README.md).
+
+```bash
+npm install -g @odingard/guardian-mcp
+```
+
+```json
+{
+  "mcpServers": {
+    "guardian": {
+      "command": "guardian-mcp",
+      "env": {
+        "GUARDIAN_BASE_URL": "https://guardian-api.odingard.com",
+        "GUARDIAN_AGENT_CREDENTIAL": "gac1.…",
+        "GUARDIAN_CONNECTION_ID": "con_…"
+      }
+    }
+  }
+}
+```
+
+## Plans and limits
+
+Guardian is free for individuals — no card required, with the same core
+authority protections on every plan. Usage is metered per month on
+protected actions (the consequential things an agent can cause); reading
+receipts and requests is never metered.
+
+| Plan | Price | Connections | Agents | Protected actions / month |
+|------|-------|-------------|--------|---------------------------|
+| Free | $0 | 1 | 1 | 50 |
+| Guardian Personal | $19/month or $190/year | 10 | 25 | 50,000 |
+| Guardian Family | $39/month or $390/year | 50 | 250 | 500,000 |
+| Guardian Developer | $99/month plus protected-action usage | 250 | 1,000 | 5,000,000 |
+
+Over a limit, the API returns `403 PLAN_LIMIT_EXCEEDED` naming your plan,
+the limit, and current usage. Upgrade in the console → Billing
+(`POST /v1/billing/checkout` with `{plan, interval}` issues a Stripe
+Checkout URL; monthly and annual billing are both offered).
+
+## Framework adapters
+
+Drop-in wrappers that put an agent framework's tool calls behind the same
+ALLOW / ASK / DENY triad — nothing runs before a decision, and no tool
+ever runs without a capability issued for that exact call.
+
+Two execution modes, per tool or per wrapper (`mode` / `modes` options):
+
+- `remote` (default): the tool name is a registered Guardian catalog
+  entry — a bounded HTTP(S) call Guardian performs itself on `ALLOW`.
+  `client.execute` IS the execution; the call resolves to the ALLOW
+  receipt and the local impl never runs.
+- `inProcess` (opt-in): the local impl IS the tool. It runs only after
+  the capability is issued, then `client.execute` redeems + records the
+  evidence — needs a `transport: "record"` catalog entry, auto-installed
+  via `mcp.install` on first use (WO-021 control plane required).
+
+### `remote` vs `inProcess` — read this
+
+`remote` (default): Guardian holds the effect. Nothing local runs; after ALLOW
+the SDK calls `execute` and Guardian's adapter performs the action.
+
+`inProcess`: your local tool body runs **after an ALLOW decision but before the
+capability is redeemed**. Redemption-time checks (revocation, expiry,
+single-use) therefore land after the effect, and the effect itself is not
+mediated by Guardian. It is decision-gated, not pre-execution enforcement. If
+redemption then fails, `GuardianExecutionFailed.localEffectRan === true` —
+treat it as an incident. Use `remote` wherever Guardian must hold the effect.
+
+### Vercel AI SDK — `@odingard/guardian-vercel-ai`
+
+```bash
+npm install @odingard/guardian-vercel-ai
+```
+
+```ts
+import { createGuardianClient } from "@odingard/guardian-sdk";
+import { GuardianApprovalPending, GuardianDenied, withGuardian }
+  from "@odingard/guardian-vercel-ai";
+
+const guardian = createGuardianClient({ baseUrl, credential });
+const tools = withGuardian({ refund_order, send_email }, {
+  client: guardian,
+  connectionId: "con_…",
+  agentName: "billing-agent",
+  modes: { refund_order: "inProcess" }, // send_email stays remote
+});
+
+// ALLOW remote: client.execute performs the catalog call, call resolves
+//   to the ALLOW receipt. ALLOW inProcess: local impl runs, then
+//   execute redeems + records it, call resolves to the impl output.
+// ASK: GuardianApprovalPending carries requestId — approve in Guardian,
+//   then `await pending.resume()`. DENY: GuardianDenied carries
+//   reasonCode; nothing executes. onAsk/onDeny: "result" returns a
+//   serializable decision to the model instead of throwing.
+```
+
+### LangChain.js — `@odingard/guardian-langchain`
+
+```bash
+npm install @odingard/guardian-langchain
+```
+
+```ts
+import { createGuardianClient } from "@odingard/guardian-sdk";
+import { GuardianApprovalPending, GuardianDenied, guardianTool }
+  from "@odingard/guardian-langchain";
+
+const guardian = createGuardianClient({ baseUrl, credential });
+const refundOrder = guardianTool(refundOrderTool, {
+  client: guardian,
+  connectionId: "con_…",
+  mode: "inProcess",
+});
+
+// Same triad + modes: the wrapped tool keeps its name, description,
+// schema and returnDirect flag, so it drops into bindTools / LangGraph
+// unchanged. On ASK, catch GuardianApprovalPending in your node and
+// interrupt() — pending.resume() claims the capability and completes
+// the call after the human approves.
+```
+
+## Examples
+
+Runnable examples live in [`examples/`](examples/). Each prints its label:
+`SIMULATED` = a local demo policy stands in for Guardian (nothing real
+happens); `LIVE` = real hosted Guardian (set `GUARDIAN_BASE_URL`,
+`GUARDIAN_AGENT_CREDENTIAL`, `GUARDIAN_CONNECTION_ID`) or real published keys.
+
+```bash
+cd examples && npm install
+
+node verify-receipt.mjs         # LIVE, no account: verify a real staging receipt offline, then tamper
+node demo-classes.mjs           # the 7 demo classes (email, delegation, vendor payment, PHI, deploy, CRM, robot stop)
+node steel-checkout.mjs         # Steel checkout → ASK → resume
+node shopping-agent.mjs         # purchase → ASK, human approves, receipt
+node prompt-injection-deny.mjs  # injected "export contacts" → DENY
+node coding-agent-ask.mjs       # consequential command → ASK
+```
+
 ## License
 
 Apache-2.0
 
 ## Provenance
 
-Canonical development happens in the Odingard Guardian monorepo; this
-repository is the standalone open-source distribution of the agent SDK
+Canonical development happens in the [Odingard Guardian monorepo](https://github.com/Odingard/guardian);
+this repository is the standalone open-source distribution of the agent SDK
 (source mirrored, Apache-2.0). Issues and contributions welcome here.