@odingard/guardian-sdk 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,303 @@
-# Temporary Holding Version
+<p align="center">
+  <img src=".github/assets/guardian-logo.png" alt="Guardian — human authority for AI" width="640" />
+</p>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @odingard/guardian-sdk
+
+[![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: [guardian.odingard.com](https://guardian.odingard.com) — free tier for developers
+(1 agent, 1 connection, 50 protected actions/month), no card required.
+
+## Install
+
+```bash
+npm install @odingard/guardian-sdk
+```
+
+Requires Node.js >= 22 (receipt verification uses `node:crypto` Ed25519; browser runtimes are not supported in 0.2).
+
+## Quickstart
+
+```ts
+import { classifyRequestResult, createGuardianClient } from "@odingard/guardian-sdk";
+
+const guardian = createGuardianClient({
+  baseUrl: "https://guardian-api.odingard.com",
+  credential: process.env.GUARDIAN_AGENT_CREDENTIAL!, // gac1.… issued per agent
+});
+
+// 1. The agent asks for a capability — it never holds real credentials.
+const result = await guardian.request({
+  action: "tool.invoke",
+  connectionId: "con_…",
+  toolName: "refund_order",
+  arguments: { orderId: "ord_123" },
+});
+
+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: d.requestId,
+    capabilityToken: d.capabilityToken,
+  });
+  console.log(execution.ok ? execution.receipt : execution.reasonCode);
+} 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".
+}
+// 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
+
+- The agent only ever holds a scoped, revocable agent credential (`gac1.…`).
+- Provider secrets (API keys, OAuth tokens) live in the Guardian vault and are
+  leased to the adapter at execution time — the agent never sees them.
+- `ASK` decisions wait for a human. `DENY` stops the action before execution.
+- `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](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.