@vantic/sdk 0.1.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 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

@@ -0,0 +1,42 @@
+# @vantic/sdk
+
+Signed mandates and receipt chains for autonomous agent transactions — and a
+client-side spending firewall so your agent can't be prompt-injected into paying an attacker.
+
+Zero runtime dependencies (Node ≥ 18 built-in crypto). Ed25519 + SHA-256 + canonical JSON,
+with `did:key`/`did:web` identity and W3C Verifiable Credentials for the sponsor chain.
+
+```bash
+npm install @vantic/sdk
+```
+
+```ts
+import { generateKeyPair, issueMandate, AgentWallet } from "@vantic/sdk";
+
+const principal = generateKeyPair();
+const agent = generateKeyPair();
+
+const mandate = issueMandate({
+  agent: agent.publicKey,
+  principal: principal.publicKey,
+  principalPrivateKeyPem: principal.privateKeyPem,
+  ttlSeconds: 7 * 24 * 3600,
+  scope: {
+    budget: { currency: "USD", amount: 50000, windowSeconds: 7 * 24 * 3600 }, // $500 / 7d
+    maxPerTransaction: 20000,
+    allowedActions: ["purchase"],
+    allowedCounterparties: ["etsy.com", "*.shop.example"],
+  },
+});
+
+// Wrap your agent's spend calls. A blocked action throws BEFORE any money moves.
+const wallet = new AgentWallet(mandate, agent.privateKeyPem);
+await wallet.spend(
+  { type: "purchase", counterparty: "etsy.com", amount: 4500, currency: "USD" },
+  async (a) => ({ outcome: "settled", result: await pay(a) }),
+);
+```
+
+Also ships as an MCP server (`npx vantic-mcp`) exposing stateless verification tools.
+
+Full docs, protocol spec, and demos: see the repository. Apache-2.0.

package/dist/adapters.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Framework adapters — drop Vantic into an existing agent with one wrap, not a rewrite.
+ *
+ * Agent frameworks (MCP, LangChain, OpenAI function-calling) all expose "tools": functions
+ * the model invokes with JSON args that produce a side effect. `guardTool` wraps any such
+ * money-moving tool so every call flows through the AgentWallet firewall automatically.
+ * `wrapMcpTool` is the MCP-shaped convenience: a blocked call returns a structured tool
+ * error the model can read and reason about, and — critically — the underlying side effect
+ * never runs.
+ */
+import { AgentWallet } from "./guard.js";
+import type { Action, Outcome, Receipt } from "./types.js";
+export type GuardedToolResponse<T> = {
+    ok: true;
+    receipt: Receipt;
+    result?: T;
+} | {
+    ok: false;
+    blocked: true;
+    reasons: string[];
+};
+export interface GuardToolOptions<Args, T> {
+    wallet: AgentWallet;
+    /** Map the tool's call arguments to a Vantic Action (type/counterparty/amount/currency). */
+    toAction: (args: Args) => Action;
+    /** The real side effect (charge card, submit x402, call purchase API). Runs only if authorized. */
+    execute: (args: Args) => Promise<{
+        outcome: Outcome;
+        result?: T;
+    }> | {
+        outcome: Outcome;
+        result?: T;
+    };
+    /** Throw GuardViolation on block instead of returning a structured denial. Default: false. */
+    throwOnBlock?: boolean;
+}
+/**
+ * Wrap a money-moving tool handler so it is gated by the wallet. The returned function has
+ * the same call shape; on a blocked action `execute` is never called and no money moves.
+ */
+export declare function guardTool<Args, T>(opts: GuardToolOptions<Args, T>): (args: Args) => Promise<GuardedToolResponse<T>>;
+export interface McpToolResult {
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    isError?: boolean;
+}
+export interface McpTool {
+    name: string;
+    description?: string;
+    inputSchema: Record<string, unknown>;
+    handler: (args: any) => Promise<McpToolResult> | McpToolResult;
+}
+export interface WrapMcpOptions {
+    wallet: AgentWallet;
+    /** Map the MCP tool's arguments to a Vantic Action. */
+    toAction: (args: any) => Action;
+}
+/**
+ * Wrap an MCP tool definition so its handler is guarded by the wallet. A blocked call
+ * returns `{ isError: true }` with a readable reason (the model sees it and can adjust);
+ * the wrapped tool's original handler runs only when the action is authorized.
+ */
+export declare function wrapMcpTool(tool: McpTool, opts: WrapMcpOptions): McpTool;
+//# sourceMappingURL=adapters.d.ts.map

package/dist/adapters.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapters.d.ts","sourceRoot":"","sources":["../src/adapters.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAE,WAAW,EAAkB,MAAM,YAAY,CAAC;AACzD,OAAO,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAE3D,MAAM,MAAM,mBAAmB,CAAC,CAAC,IAC7B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,OAAO,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,CAAC,CAAA;CAAE,GAC1C;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,IAAI,CAAC;IAAC,OAAO,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC;AAEpD,MAAM,WAAW,gBAAgB,CAAC,IAAI,EAAE,CAAC;IACvC,MAAM,EAAE,WAAW,CAAC;IACpB,4FAA4F;IAC5F,QAAQ,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,MAAM,CAAC;IACjC,mGAAmG;IACnG,OAAO,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,CAAC,CAAA;KAAE,CAAC,GAAG;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,CAAC,CAAA;KAAE,CAAC;IACtG,8FAA8F;IAC9F,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,CAAC,EAAE,IAAI,EAAE,gBAAgB,CAAC,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,KAAK,OAAO,CAAC,mBAAmB,CAAC,CAAC,CAAC,CAAC,CAcnH;AAGD,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC/C,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,OAAO,EAAE,CAAC,IAAI,EAAE,GAAG,KAAK,OAAO,CAAC,aAAa,CAAC,GAAG,aAAa,CAAC;CAChE;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,WAAW,CAAC;IACpB,uDAAuD;IACvD,QAAQ,EAAE,CAAC,IAAI,EAAE,GAAG,KAAK,MAAM,CAAC;CACjC;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,cAAc,GAAG,OAAO,CA6BxE"}

package/dist/adapters.js

@@ -0,0 +1,67 @@
+/**
+ * Framework adapters — drop Vantic into an existing agent with one wrap, not a rewrite.
+ *
+ * Agent frameworks (MCP, LangChain, OpenAI function-calling) all expose "tools": functions
+ * the model invokes with JSON args that produce a side effect. `guardTool` wraps any such
+ * money-moving tool so every call flows through the AgentWallet firewall automatically.
+ * `wrapMcpTool` is the MCP-shaped convenience: a blocked call returns a structured tool
+ * error the model can read and reason about, and — critically — the underlying side effect
+ * never runs.
+ */
+import { GuardViolation } from "./guard.js";
+/**
+ * Wrap a money-moving tool handler so it is gated by the wallet. The returned function has
+ * the same call shape; on a blocked action `execute` is never called and no money moves.
+ */
+export function guardTool(opts) {
+    return async (args) => {
+        const action = opts.toAction(args);
+        try {
+            const { receipt, result } = await opts.wallet.spend(action, () => opts.execute(args));
+            return { ok: true, receipt, result };
+        }
+        catch (e) {
+            if (e instanceof GuardViolation) {
+                if (opts.throwOnBlock)
+                    throw e;
+                return { ok: false, blocked: true, reasons: e.reasons };
+            }
+            throw e;
+        }
+    };
+}
+/**
+ * Wrap an MCP tool definition so its handler is guarded by the wallet. A blocked call
+ * returns `{ isError: true }` with a readable reason (the model sees it and can adjust);
+ * the wrapped tool's original handler runs only when the action is authorized.
+ */
+export function wrapMcpTool(tool, opts) {
+    const guarded = guardTool({
+        wallet: opts.wallet,
+        toAction: opts.toAction,
+        execute: async (args) => {
+            const res = await tool.handler(args);
+            return { outcome: (res.isError ? "failed" : "settled"), result: res };
+        },
+        throwOnBlock: false,
+    });
+    return {
+        ...tool,
+        handler: async (args) => {
+            const r = await guarded(args);
+            if (!r.ok) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `PAYMENT BLOCKED BY MANDATE — this action is not authorized: ${r.reasons.join("; ")}`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            return r.result ?? { content: [{ type: "text", text: "ok" }] };
+        },
+    };
+}
+//# sourceMappingURL=adapters.js.map

package/dist/adapters.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapters.js","sourceRoot":"","sources":["../src/adapters.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAe,cAAc,EAAE,MAAM,YAAY,CAAC;AAiBzD;;;GAGG;AACH,MAAM,UAAU,SAAS,CAAU,IAA+B;IAChE,OAAO,KAAK,EAAE,IAAU,EAAE,EAAE;QAC1B,MAAM,MAAM,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;QACnC,IAAI,CAAC;YACH,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,KAAK,CAAI,MAAM,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;YACzF,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC;QACvC,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,IAAI,CAAC,YAAY,cAAc,EAAE,CAAC;gBAChC,IAAI,IAAI,CAAC,YAAY;oBAAE,MAAM,CAAC,CAAC;gBAC/B,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC;YAC1D,CAAC;YACD,MAAM,CAAC,CAAC;QACV,CAAC;IACH,CAAC,CAAC;AACJ,CAAC;AAqBD;;;;GAIG;AACH,MAAM,UAAU,WAAW,CAAC,IAAa,EAAE,IAAoB;IAC7D,MAAM,OAAO,GAAG,SAAS,CAAqB;QAC5C,MAAM,EAAE,IAAI,CAAC,MAAM;QACnB,QAAQ,EAAE,IAAI,CAAC,QAAQ;QACvB,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE;YACtB,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;YACrC,OAAO,EAAE,OAAO,EAAE,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAY,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC;QACnF,CAAC;QACD,YAAY,EAAE,KAAK;KACpB,CAAC,CAAC;IAEH,OAAO;QACL,GAAG,IAAI;QACP,OAAO,EAAE,KAAK,EAAE,IAAS,EAA0B,EAAE;YACnD,MAAM,CAAC,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;YAC9B,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;gBACV,OAAO;oBACL,OAAO,EAAE;wBACP;4BACE,IAAI,EAAE,MAAM;4BACZ,IAAI,EAAE,+DAA+D,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE;yBAC5F;qBACF;oBACD,OAAO,EAAE,IAAI;iBACd,CAAC;YACJ,CAAC;YACD,OAAO,CAAC,CAAC,MAAM,IAAI,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC;QACjE,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/credential.d.ts

@@ -0,0 +1,51 @@
+import type { ISO8601 } from "./types.js";
+export interface CredentialProof {
+    type: "Ed25519Signature2020";
+    created: ISO8601;
+    verificationMethod: string;
+    proofPurpose: "assertionMethod";
+    /** base64url Ed25519 signature over the canonical credential (sans proof). */
+    proofValue: string;
+}
+export interface SponsorCredential {
+    "@context": string[];
+    type: string[];
+    /** Issuer DID (the sponsor / principal). */
+    issuer: string;
+    issuanceDate: ISO8601;
+    expirationDate?: ISO8601;
+    credentialSubject: {
+        /** Subject DID (the agent). */
+        id: string;
+        role: "authorized-agent";
+        sponsor: string;
+        [key: string]: unknown;
+    };
+    proof?: CredentialProof;
+}
+export interface IssueSponsorCredentialParams {
+    /** Issuer (principal) DID — `did:key:...`. */
+    issuerDid: string;
+    /** Issuer's PKCS#8 PEM private key. */
+    issuerPrivateKeyPem: string;
+    /** Subject (agent) DID — `did:key:...`. */
+    subjectDid: string;
+    /** Optional extra claims merged into credentialSubject. */
+    claims?: Record<string, unknown>;
+    /** Optional validity in seconds from `now`. */
+    ttlSeconds?: number;
+    now?: Date;
+}
+/** Issue and sign a sponsor credential. */
+export declare function issueSponsorCredential(params: IssueSponsorCredentialParams): SponsorCredential;
+export interface CredentialVerifyOptions {
+    now?: Date;
+    /** If set, require the credential's subject DID to equal this. */
+    expectSubject?: string;
+}
+/** Verify a sponsor credential's proof, issuer binding, and validity window. */
+export declare function verifySponsorCredential(cred: SponsorCredential, opts?: CredentialVerifyOptions): {
+    ok: boolean;
+    reasons: string[];
+};
+//# sourceMappingURL=credential.d.ts.map

package/dist/credential.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"credential.d.ts","sourceRoot":"","sources":["../src/credential.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAE1C,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,sBAAsB,CAAC;IAC7B,OAAO,EAAE,OAAO,CAAC;IACjB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,YAAY,EAAE,iBAAiB,CAAC;IAChC,8EAA8E;IAC9E,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,iBAAiB;IAChC,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,4CAA4C;IAC5C,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,OAAO,CAAC;IACtB,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,iBAAiB,EAAE;QACjB,+BAA+B;QAC/B,EAAE,EAAE,MAAM,CAAC;QACX,IAAI,EAAE,kBAAkB,CAAC;QACzB,OAAO,EAAE,MAAM,CAAC;QAChB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;KACxB,CAAC;IACF,KAAK,CAAC,EAAE,eAAe,CAAC;CACzB;AAED,MAAM,WAAW,4BAA4B;IAC3C,8CAA8C;IAC9C,SAAS,EAAE,MAAM,CAAC;IAClB,uCAAuC;IACvC,mBAAmB,EAAE,MAAM,CAAC;IAC5B,2CAA2C;IAC3C,UAAU,EAAE,MAAM,CAAC;IACnB,2DAA2D;IAC3D,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,+CAA+C;IAC/C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,GAAG,CAAC,EAAE,IAAI,CAAC;CACZ;AAMD,2CAA2C;AAC3C,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,4BAA4B,GAAG,iBAAiB,CA4B9F;AAED,MAAM,WAAW,uBAAuB;IACtC,GAAG,CAAC,EAAE,IAAI,CAAC;IACX,kEAAkE;IAClE,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,gFAAgF;AAChF,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,iBAAiB,EAAE,IAAI,GAAE,uBAA4B,GAAG;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,EAAE,CAAA;CAAE,CAkCvI"}

package/dist/credential.js

@@ -0,0 +1,78 @@
+/**
+ * Sponsor credential — a minimal W3C Verifiable Credential asserting the human/org sponsor
+ * relationship for an agent (the human sponsor chain). This is separate
+ * from any single envelope: it is a portable, verifiable statement "principal P sponsors
+ * agent A", which a counterparty can check once and cache, independent of individual mandates.
+ *
+ * Shape follows W3C VC Data Model with an Ed25519 proof. Issuer/subject are DIDs.
+ */
+import { canonicalize, signBytes, verifyBytes } from "./crypto.js";
+import { isDidKey, keyIdToDidKey, isKeyId } from "./did.js";
+function toDid(id) {
+    return isKeyId(id) ? keyIdToDidKey(id) : id;
+}
+/** Issue and sign a sponsor credential. */
+export function issueSponsorCredential(params) {
+    const now = params.now ?? new Date();
+    const issuer = toDid(params.issuerDid);
+    const subject = toDid(params.subjectDid);
+    const unsigned = {
+        "@context": ["https://www.w3.org/ns/credentials/v2"],
+        type: ["VerifiableCredential", "AgentSponsorship"],
+        issuer,
+        issuanceDate: now.toISOString(),
+        ...(params.ttlSeconds ? { expirationDate: new Date(now.getTime() + params.ttlSeconds * 1000).toISOString() } : {}),
+        credentialSubject: {
+            id: subject,
+            role: "authorized-agent",
+            sponsor: issuer,
+            ...(params.claims ?? {}),
+        },
+    };
+    const bytes = Buffer.from(canonicalize(unsigned), "utf8");
+    const proof = {
+        type: "Ed25519Signature2020",
+        created: now.toISOString(),
+        verificationMethod: isDidKey(issuer) ? `${issuer}#${issuer.slice("did:key:".length)}` : issuer,
+        proofPurpose: "assertionMethod",
+        proofValue: signBytes(params.issuerPrivateKeyPem, bytes),
+    };
+    return { ...unsigned, proof };
+}
+/** Verify a sponsor credential's proof, issuer binding, and validity window. */
+export function verifySponsorCredential(cred, opts = {}) {
+    const now = opts.now ?? new Date();
+    const reasons = [];
+    if (!cred.proof) {
+        return { ok: false, reasons: ["missing proof"] };
+    }
+    if (!isDidKey(cred.issuer)) {
+        // did:web (or other) verification requires resolution; out of scope for the sync path.
+        reasons.push(`issuer is not a did:key (got ${cred.issuer}); resolve its key to verify`);
+    }
+    // The proof's verificationMethod must belong to the issuer.
+    if (!cred.proof.verificationMethod.startsWith(cred.issuer)) {
+        reasons.push("proof.verificationMethod does not match issuer");
+    }
+    // credentialSubject.sponsor must equal issuer (the sponsor-chain assertion).
+    if (cred.credentialSubject.sponsor !== cred.issuer) {
+        reasons.push("credentialSubject.sponsor does not match issuer");
+    }
+    if (opts.expectSubject && cred.credentialSubject.id !== opts.expectSubject) {
+        reasons.push(`subject mismatch: expected ${opts.expectSubject}`);
+    }
+    // Validity window.
+    if (new Date(cred.issuanceDate).getTime() > now.getTime())
+        reasons.push("credential not yet valid");
+    if (cred.expirationDate && new Date(cred.expirationDate).getTime() <= now.getTime())
+        reasons.push("credential expired");
+    // Signature (only checkable synchronously for did:key issuers).
+    if (isDidKey(cred.issuer)) {
+        const { proof, ...unsigned } = cred;
+        const bytes = Buffer.from(canonicalize(unsigned), "utf8");
+        if (!verifyBytes(cred.issuer, bytes, proof.proofValue))
+            reasons.push("credential proof signature invalid");
+    }
+    return { ok: reasons.length === 0, reasons };
+}
+//# sourceMappingURL=credential.js.map

package/dist/credential.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"credential.js","sourceRoot":"","sources":["../src/credential.ts"],"names":[],"mappings":"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"}

package/dist/crypto.d.ts

@@ -0,0 +1,27 @@
+import type { KeyId, KeyPair, Signature } from "./types.js";
+/** Generate a fresh Ed25519 keypair with both a `key:<x>` id and its `did:key` form. */
+export declare function generateKeyPair(): KeyPair;
+/** Sign bytes with a PKCS#8 PEM Ed25519 private key; returns base64url. */
+export declare function signBytes(privateKeyPem: string, data: Buffer): string;
+/** Verify a base64url Ed25519 signature against a `key:<x>` id. Never throws. */
+export declare function verifyBytes(keyId: KeyId, data: Buffer, signatureB64url: string): boolean;
+/** SHA-256, hex-encoded. */
+export declare function sha256Hex(data: Buffer | string): string;
+/** A UUID for envelope/receipt ids. */
+export declare function newId(): string;
+/**
+ * Canonical JSON serialization (JCS-compatible subset, RFC 8785 target):
+ * object keys sorted lexicographically, no insignificant whitespace, UTF-8.
+ * Amounts are integers by protocol rule (§4.1), so number formatting is unambiguous.
+ */
+export declare function canonicalize(value: unknown): string;
+/**
+ * Produce a Signature over an object, excluding any existing `signature` field.
+ * Used to sign both envelopes (by principal) and receipts (by agent).
+ */
+export declare function signObject(obj: Record<string, unknown>, by: KeyId, privateKeyPem: string): Signature;
+/** Verify an object's embedded Signature was produced by `expectedSigner`. */
+export declare function verifyObjectSignature(obj: Record<string, unknown> & {
+    signature?: Signature;
+}, expectedSigner: KeyId): boolean;
+//# sourceMappingURL=crypto.d.ts.map

package/dist/crypto.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"crypto.d.ts","sourceRoot":"","sources":["../src/crypto.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAG5D,wFAAwF;AACxF,wBAAgB,eAAe,IAAI,OAAO,CAUzC;AAWD,2EAA2E;AAC3E,wBAAgB,SAAS,CAAC,aAAa,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAIrE;AAED,iFAAiF;AACjF,wBAAgB,WAAW,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,GAAG,OAAO,CAOxF;AAED,4BAA4B;AAC5B,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAEvD;AAED,uCAAuC;AACvC,wBAAgB,KAAK,IAAI,MAAM,CAE9B;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAmBnD;AAED;;;GAGG;AACH,wBAAgB,UAAU,CACxB,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5B,EAAE,EAAE,KAAK,EACT,aAAa,EAAE,MAAM,GACpB,SAAS,CAIX;AAED,8EAA8E;AAC9E,wBAAgB,qBAAqB,CACnC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG;IAAE,SAAS,CAAC,EAAE,SAAS,CAAA;CAAE,EACxD,cAAc,EAAE,KAAK,GACpB,OAAO,CAOT"}