@vantic/sdk 0.1.0

package/dist/crypto.js

@@ -0,0 +1,103 @@
+/**
+ * Cryptographic primitives for Vantic. Ed25519 + SHA-256 + canonical JSON.
+ * Zero external dependencies — uses Node's built-in `node:crypto`.
+ */
+import * as crypto from "node:crypto";
+import { didKeyFromRaw, identifierToJwkX } from "./did.js";
+/** Generate a fresh Ed25519 keypair with both a `key:<x>` id and its `did:key` form. */
+export function generateKeyPair() {
+    const { publicKey, privateKey } = crypto.generateKeyPairSync("ed25519");
+    const jwk = publicKey.export({ format: "jwk" });
+    if (!jwk.x)
+        throw new Error("failed to derive public key");
+    const raw = Buffer.from(jwk.x, "base64url");
+    return {
+        publicKey: `key:${jwk.x}`,
+        did: didKeyFromRaw(raw),
+        privateKeyPem: privateKey.export({ format: "pem", type: "pkcs8" }).toString(),
+    };
+}
+/** Resolve any supported identifier (`key:<x>` or `did:key:z...`) to a public KeyObject. */
+function publicKeyObjectFromId(identifier) {
+    const x = identifierToJwkX(identifier); // handles both key: and did:key:
+    return crypto.createPublicKey({
+        key: { kty: "OKP", crv: "Ed25519", x },
+        format: "jwk",
+    });
+}
+/** Sign bytes with a PKCS#8 PEM Ed25519 private key; returns base64url. */
+export function signBytes(privateKeyPem, data) {
+    const key = crypto.createPrivateKey(privateKeyPem);
+    // For Ed25519 the digest algorithm argument must be null.
+    return crypto.sign(null, data, key).toString("base64url");
+}
+/** Verify a base64url Ed25519 signature against a `key:<x>` id. Never throws. */
+export function verifyBytes(keyId, data, signatureB64url) {
+    try {
+        const key = publicKeyObjectFromId(keyId);
+        return crypto.verify(null, data, key, Buffer.from(signatureB64url, "base64url"));
+    }
+    catch {
+        return false;
+    }
+}
+/** SHA-256, hex-encoded. */
+export function sha256Hex(data) {
+    return crypto.createHash("sha256").update(data).digest("hex");
+}
+/** A UUID for envelope/receipt ids. */
+export function newId() {
+    return crypto.randomUUID();
+}
+/**
+ * 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 function canonicalize(value) {
+    if (value === null)
+        return "null";
+    const t = typeof value;
+    if (t === "number") {
+        if (!Number.isFinite(value))
+            throw new Error("non-finite number cannot be canonicalized");
+        return JSON.stringify(value);
+    }
+    if (t === "boolean")
+        return value ? "true" : "false";
+    if (t === "string")
+        return JSON.stringify(value);
+    if (t === "undefined")
+        throw new Error("undefined cannot be canonicalized");
+    if (Array.isArray(value))
+        return `[${value.map(canonicalize).join(",")}]`;
+    if (t === "object") {
+        const obj = value;
+        const keys = Object.keys(obj)
+            .filter((k) => obj[k] !== undefined)
+            .sort();
+        return `{${keys.map((k) => `${JSON.stringify(k)}:${canonicalize(obj[k])}`).join(",")}}`;
+    }
+    throw new Error(`unsupported type in canonicalize: ${t}`);
+}
+/**
+ * Produce a Signature over an object, excluding any existing `signature` field.
+ * Used to sign both envelopes (by principal) and receipts (by agent).
+ */
+export function signObject(obj, by, privateKeyPem) {
+    const { signature: _drop, ...unsigned } = obj;
+    const bytes = Buffer.from(canonicalize(unsigned), "utf8");
+    return { alg: "Ed25519", by, value: signBytes(privateKeyPem, bytes) };
+}
+/** Verify an object's embedded Signature was produced by `expectedSigner`. */
+export function verifyObjectSignature(obj, expectedSigner) {
+    const sig = obj.signature;
+    if (!sig || sig.alg !== "Ed25519")
+        return false;
+    if (sig.by !== expectedSigner)
+        return false;
+    const { signature: _drop, ...unsigned } = obj;
+    const bytes = Buffer.from(canonicalize(unsigned), "utf8");
+    return verifyBytes(sig.by, bytes, sig.value);
+}
+//# sourceMappingURL=crypto.js.map

package/dist/crypto.js.map

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

package/dist/did.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Decentralized Identifiers (DIDs) for Vantic — W3C `did:key` (self-contained) and
+ * `did:web` scaffolding. This upgrades a principal/agent identifier from "a bare public
+ * key" to "a resolvable, standard, verifiable identity" without changing the protocol:
+ * envelopes and receipts can use either `key:<x>` or `did:key:z...` identifiers, and the
+ * crypto layer resolves both to the same Ed25519 key.
+ *
+ * Zero dependencies: base58btc + multicodec implemented inline.
+ */
+import type { KeyId } from "./types.js";
+export declare function base58Encode(bytes: Uint8Array): string;
+export declare function base58Decode(str: string): Uint8Array;
+/** Multibase key fragment, e.g. "z6Mk..." — the part after `did:key:` and after `#`. */
+export declare function multibaseFromRaw(raw: Buffer): string;
+/** Raw 32-byte Ed25519 public key from a `z...` multibase string. */
+export declare function rawFromMultibase(multibase: string): Buffer;
+export declare function didKeyFromRaw(raw: Buffer): string;
+export declare function rawFromDidKey(did: string): Buffer;
+export declare function isDidKey(id: string): boolean;
+export declare function isKeyId(id: string): boolean;
+export declare function isDid(id: string): boolean;
+/** Raw Ed25519 public key bytes from any supported identifier. */
+export declare function identifierToRaw(identifier: KeyId): Buffer;
+/** JWK `x` (base64url raw public key) from any supported identifier — used by the crypto layer. */
+export declare function identifierToJwkX(identifier: KeyId): string;
+export declare function keyIdFromRaw(raw: Buffer): KeyId;
+/** Convert between the two identifier forms for the same key. */
+export declare function keyIdToDidKey(keyId: KeyId): string;
+export declare function didKeyToKeyId(did: string): KeyId;
+export interface VerificationMethod {
+    id: string;
+    type: "Ed25519VerificationKey2020";
+    controller: string;
+    publicKeyMultibase: string;
+}
+export interface DIDDocument {
+    "@context": string[];
+    id: string;
+    verificationMethod: VerificationMethod[];
+    authentication: string[];
+    assertionMethod: string[];
+}
+/** Resolve a did:key to its DID Document synchronously (the key IS the document). */
+export declare function resolveDidKey(did: string): DIDDocument;
+/** Map a did:web identifier to the URL of its DID document. */
+export declare function didWebToUrl(did: string): string;
+/** Build a publishable did:web DID Document for a raw Ed25519 key (host it at the URL above). */
+export declare function buildDidWebDocument(did: string, raw: Buffer): DIDDocument;
+/** A DID resolver: did:key is handled synchronously; did:web is delegated to `fetchJson`. */
+export interface DidResolver {
+    resolve(did: string): Promise<DIDDocument>;
+}
+export declare function createResolver(fetchJson?: (url: string) => Promise<unknown>): DidResolver;
+//# sourceMappingURL=did.d.ts.map

package/dist/did.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"did.d.ts","sourceRoot":"","sources":["../src/did.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAKxC,wBAAgB,YAAY,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAkBtD;AAED,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,CAiBpD;AAKD,wFAAwF;AACxF,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAGpD;AAED,qEAAqE;AACrE,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAK1D;AAED,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEjD;AAED,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAGjD;AAGD,wBAAgB,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAE5C;AACD,wBAAgB,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAE3C;AACD,wBAAgB,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAEzC;AAED,kEAAkE;AAClE,wBAAgB,eAAe,CAAC,UAAU,EAAE,KAAK,GAAG,MAAM,CAIzD;AAED,mGAAmG;AACnG,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,KAAK,GAAG,MAAM,CAE1D;AAED,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,KAAK,CAE/C;AAED,iEAAiE;AACjE,wBAAgB,aAAa,CAAC,KAAK,EAAE,KAAK,GAAG,MAAM,CAElD;AACD,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,KAAK,CAEhD;AAGD,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,4BAA4B,CAAC;IACnC,UAAU,EAAE,MAAM,CAAC;IACnB,kBAAkB,EAAE,MAAM,CAAC;CAC5B;AACD,MAAM,WAAW,WAAW;IAC1B,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,EAAE,EAAE,MAAM,CAAC;IACX,kBAAkB,EAAE,kBAAkB,EAAE,CAAC;IACzC,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,eAAe,EAAE,MAAM,EAAE,CAAC;CAC3B;AAED,qFAAqF;AACrF,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,WAAW,CAWtD;AAGD,+DAA+D;AAC/D,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAS/C;AAED,iGAAiG;AACjG,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,WAAW,CAUzE;AAED,6FAA6F;AAC7F,MAAM,WAAW,WAAW;IAC1B,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;CAC5C;AAED,wBAAgB,cAAc,CAAC,SAAS,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,GAAG,WAAW,CAWzF"}

package/dist/did.js

@@ -0,0 +1,152 @@
+// ── base58btc (Bitcoin alphabet) ────────────────────────────────────────────────────────
+const B58 = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz";
+export function base58Encode(bytes) {
+    const digits = [];
+    for (const byte of bytes) {
+        let carry = byte;
+        for (let i = 0; i < digits.length; i++) {
+            carry += digits[i] << 8;
+            digits[i] = carry % 58;
+            carry = (carry / 58) | 0;
+        }
+        while (carry > 0) {
+            digits.push(carry % 58);
+            carry = (carry / 58) | 0;
+        }
+    }
+    let out = "";
+    for (let i = 0; i < bytes.length && bytes[i] === 0; i++)
+        out += B58[0];
+    for (let i = digits.length - 1; i >= 0; i--)
+        out += B58[digits[i]];
+    return out;
+}
+export function base58Decode(str) {
+    const bytes = [];
+    for (const ch of str) {
+        let carry = B58.indexOf(ch);
+        if (carry < 0)
+            throw new Error(`invalid base58 character: ${ch}`);
+        for (let i = 0; i < bytes.length; i++) {
+            carry += bytes[i] * 58;
+            bytes[i] = carry & 0xff;
+            carry >>= 8;
+        }
+        while (carry > 0) {
+            bytes.push(carry & 0xff);
+            carry >>= 8;
+        }
+    }
+    for (let i = 0; i < str.length && str[i] === B58[0]; i++)
+        bytes.push(0);
+    return Uint8Array.from(bytes.reverse());
+}
+// ── did:key for Ed25519 (multicodec 0xed01) ──────────────────────────────────────────────
+const ED25519_MULTICODEC = Uint8Array.from([0xed, 0x01]);
+/** Multibase key fragment, e.g. "z6Mk..." — the part after `did:key:` and after `#`. */
+export function multibaseFromRaw(raw) {
+    const prefixed = Buffer.concat([Buffer.from(ED25519_MULTICODEC), raw]);
+    return "z" + base58Encode(prefixed);
+}
+/** Raw 32-byte Ed25519 public key from a `z...` multibase string. */
+export function rawFromMultibase(multibase) {
+    if (!multibase.startsWith("z"))
+        throw new Error("unsupported multibase (expected base58btc 'z')");
+    const decoded = base58Decode(multibase.slice(1));
+    if (decoded[0] !== 0xed || decoded[1] !== 0x01)
+        throw new Error("not an Ed25519 multicodec key");
+    return Buffer.from(decoded.slice(2));
+}
+export function didKeyFromRaw(raw) {
+    return `did:key:${multibaseFromRaw(raw)}`;
+}
+export function rawFromDidKey(did) {
+    if (!did.startsWith("did:key:"))
+        throw new Error("not a did:key");
+    return rawFromMultibase(did.slice("did:key:".length));
+}
+// ── Identifier helpers (support `key:<x>` and `did:key:z...`) ─────────────────────────────
+export function isDidKey(id) {
+    return id.startsWith("did:key:");
+}
+export function isKeyId(id) {
+    return id.startsWith("key:");
+}
+export function isDid(id) {
+    return id.startsWith("did:");
+}
+/** Raw Ed25519 public key bytes from any supported identifier. */
+export function identifierToRaw(identifier) {
+    if (isKeyId(identifier))
+        return Buffer.from(identifier.slice("key:".length), "base64url");
+    if (isDidKey(identifier))
+        return rawFromDidKey(identifier);
+    throw new Error(`unsupported identifier (expected key: or did:key:): ${identifier}`);
+}
+/** JWK `x` (base64url raw public key) from any supported identifier — used by the crypto layer. */
+export function identifierToJwkX(identifier) {
+    return identifierToRaw(identifier).toString("base64url");
+}
+export function keyIdFromRaw(raw) {
+    return `key:${raw.toString("base64url")}`;
+}
+/** Convert between the two identifier forms for the same key. */
+export function keyIdToDidKey(keyId) {
+    return didKeyFromRaw(identifierToRaw(keyId));
+}
+export function didKeyToKeyId(did) {
+    return keyIdFromRaw(rawFromDidKey(did));
+}
+/** Resolve a did:key to its DID Document synchronously (the key IS the document). */
+export function resolveDidKey(did) {
+    const raw = rawFromDidKey(did);
+    const mb = multibaseFromRaw(raw);
+    const vmId = `${did}#${mb}`;
+    return {
+        "@context": ["https://www.w3.org/ns/did/v1", "https://w3id.org/security/suites/ed25519-2020/v1"],
+        id: did,
+        verificationMethod: [{ id: vmId, type: "Ed25519VerificationKey2020", controller: did, publicKeyMultibase: mb }],
+        authentication: [vmId],
+        assertionMethod: [vmId],
+    };
+}
+// ── did:web scaffolding (resolution needs an HTTP fetch, injected by the caller) ──────────
+/** Map a did:web identifier to the URL of its DID document. */
+export function didWebToUrl(did) {
+    if (!did.startsWith("did:web:"))
+        throw new Error("not a did:web");
+    const rest = did.slice("did:web:".length);
+    const parts = rest.split(":").map(decodeURIComponent);
+    const host = parts[0];
+    const path = parts.slice(1);
+    return path.length === 0
+        ? `https://${host}/.well-known/did.json`
+        : `https://${host}/${path.join("/")}/did.json`;
+}
+/** Build a publishable did:web DID Document for a raw Ed25519 key (host it at the URL above). */
+export function buildDidWebDocument(did, raw) {
+    const mb = multibaseFromRaw(raw);
+    const vmId = `${did}#owner`;
+    return {
+        "@context": ["https://www.w3.org/ns/did/v1", "https://w3id.org/security/suites/ed25519-2020/v1"],
+        id: did,
+        verificationMethod: [{ id: vmId, type: "Ed25519VerificationKey2020", controller: did, publicKeyMultibase: mb }],
+        authentication: [vmId],
+        assertionMethod: [vmId],
+    };
+}
+export function createResolver(fetchJson) {
+    return {
+        async resolve(did) {
+            if (isDidKey(did))
+                return resolveDidKey(did);
+            if (did.startsWith("did:web:")) {
+                if (!fetchJson)
+                    throw new Error("did:web resolution requires a fetchJson implementation");
+                return (await fetchJson(didWebToUrl(did)));
+            }
+            throw new Error(`unsupported DID method: ${did}`);
+        },
+    };
+}
+//# sourceMappingURL=did.js.map

package/dist/did.js.map

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

package/dist/envelope.d.ts

@@ -0,0 +1,23 @@
+import { type Mandate, type KeyId, type Scope } from "./types.js";
+export interface IssueMandateParams {
+    /** Agent being authorized (its public key id). */
+    agent: KeyId;
+    /** Principal granting authority (its public key id). */
+    principal: KeyId;
+    /** Principal's PKCS#8 PEM private key — signs the envelope. */
+    principalPrivateKeyPem: string;
+    scope: Scope;
+    /** Mandate lifetime in seconds from `now`. */
+    ttlSeconds: number;
+    /** Optional revocation endpoint the verifier may consult. */
+    revocationUrl?: string;
+    /** Override the clock (testing/determinism). */
+    now?: Date;
+}
+/** Create and sign a delegation envelope. */
+export declare function issueMandate(params: IssueMandateParams): Mandate;
+/** Verify the envelope's signature is a valid Ed25519 signature by its `principal`. */
+export declare function verifyMandateSignature(env: Mandate): boolean;
+/** SHA-256 (hex) of the canonical signed envelope. Binds receipts to this exact mandate. */
+export declare function mandateHash(env: Mandate): string;
+//# sourceMappingURL=envelope.d.ts.map

package/dist/envelope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"envelope.d.ts","sourceRoot":"","sources":["../src/envelope.ts"],"names":[],"mappings":"AAKA,OAAO,EAAmB,KAAK,OAAO,EAAE,KAAK,KAAK,EAAE,KAAK,KAAK,EAAE,MAAM,YAAY,CAAC;AAEnF,MAAM,WAAW,kBAAkB;IACjC,kDAAkD;IAClD,KAAK,EAAE,KAAK,CAAC;IACb,wDAAwD;IACxD,SAAS,EAAE,KAAK,CAAC;IACjB,+DAA+D;IAC/D,sBAAsB,EAAE,MAAM,CAAC;IAC/B,KAAK,EAAE,KAAK,CAAC;IACb,8CAA8C;IAC9C,UAAU,EAAE,MAAM,CAAC;IACnB,6DAA6D;IAC7D,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,gDAAgD;IAChD,GAAG,CAAC,EAAE,IAAI,CAAC;CACZ;AAED,6CAA6C;AAC7C,wBAAgB,YAAY,CAAC,MAAM,EAAE,kBAAkB,GAAG,OAAO,CAchE;AAED,uFAAuF;AACvF,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAE5D;AAED,4FAA4F;AAC5F,wBAAgB,WAAW,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAEhD"}

package/dist/envelope.js

@@ -0,0 +1,31 @@
+/**
+ * Delegation Mandate: a signed mandate from a principal to an agent.
+ * See spec §4.
+ */
+import { canonicalize, newId, sha256Hex, signObject, verifyObjectSignature } from "./crypto.js";
+import { MANDATE_VERSION } from "./types.js";
+/** Create and sign a delegation envelope. */
+export function issueMandate(params) {
+    const now = params.now ?? new Date();
+    const base = {
+        version: MANDATE_VERSION,
+        id: newId(),
+        agent: params.agent,
+        principal: params.principal,
+        issuedAt: now.toISOString(),
+        expiresAt: new Date(now.getTime() + params.ttlSeconds * 1000).toISOString(),
+        scope: params.scope,
+        ...(params.revocationUrl ? { revocation: { url: params.revocationUrl } } : {}),
+    };
+    const signature = signObject(base, params.principal, params.principalPrivateKeyPem);
+    return { ...base, signature };
+}
+/** Verify the envelope's signature is a valid Ed25519 signature by its `principal`. */
+export function verifyMandateSignature(env) {
+    return verifyObjectSignature(env, env.principal);
+}
+/** SHA-256 (hex) of the canonical signed envelope. Binds receipts to this exact mandate. */
+export function mandateHash(env) {
+    return sha256Hex(canonicalize(env));
+}
+//# sourceMappingURL=envelope.js.map

package/dist/envelope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"envelope.js","sourceRoot":"","sources":["../src/envelope.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,YAAY,EAAE,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAChG,OAAO,EAAE,eAAe,EAAwC,MAAM,YAAY,CAAC;AAkBnF,6CAA6C;AAC7C,MAAM,UAAU,YAAY,CAAC,MAA0B;IACrD,MAAM,GAAG,GAAG,MAAM,CAAC,GAAG,IAAI,IAAI,IAAI,EAAE,CAAC;IACrC,MAAM,IAAI,GAAY;QACpB,OAAO,EAAE,eAAe;QACxB,EAAE,EAAE,KAAK,EAAE;QACX,KAAK,EAAE,MAAM,CAAC,KAAK;QACnB,SAAS,EAAE,MAAM,CAAC,SAAS;QAC3B,QAAQ,EAAE,GAAG,CAAC,WAAW,EAAE;QAC3B,SAAS,EAAE,IAAI,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,GAAG,MAAM,CAAC,UAAU,GAAG,IAAI,CAAC,CAAC,WAAW,EAAE;QAC3E,KAAK,EAAE,MAAM,CAAC,KAAK;QACnB,GAAG,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,EAAE,GAAG,EAAE,MAAM,CAAC,aAAa,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC/E,CAAC;IACF,MAAM,SAAS,GAAG,UAAU,CAAC,IAA0C,EAAE,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC,sBAAsB,CAAC,CAAC;IAC1H,OAAO,EAAE,GAAG,IAAI,EAAE,SAAS,EAAE,CAAC;AAChC,CAAC;AAED,uFAAuF;AACvF,MAAM,UAAU,sBAAsB,CAAC,GAAY;IACjD,OAAO,qBAAqB,CAAC,GAAyC,EAAE,GAAG,CAAC,SAAS,CAAC,CAAC;AACzF,CAAC;AAED,4FAA4F;AAC5F,MAAM,UAAU,WAAW,CAAC,GAAY;IACtC,OAAO,SAAS,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC;AACtC,CAAC"}

package/dist/gate.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Gate — the counterparty side.
+ *
+ * The client-side guard (AgentWallet) protects an agent from itself. This is the other
+ * half: a resource server, merchant, paid API, or another agent uses `checkMandate` to
+ * REQUIRE a valid mandate before dealing with an incoming agent — verifying that the
+ * agent's mandate is signed by a real principal and authorizes a payment to *this*
+ * counterparty, within its limits and remaining budget.
+ *
+ * This is what makes a mandate something a counterparty *requires* rather than a
+ * DIY-able self-check: the requirement lives on the receiving side, so an agent can only
+ * transact here by presenting the verifiable artifact. Nothing an agent codes on its own
+ * side satisfies a counterparty that demands a signed mandate.
+ */
+import { type VerifyOptions } from "./verify.js";
+import type { Mandate, Receipt } from "./types.js";
+export interface ResourceRequirement {
+    /** This counterparty's identifier (the resource/merchant/agent being paid). */
+    counterparty: string;
+    /** Required action type, e.g. "purchase" | "subscribe" | "pay-per-use". */
+    action: string;
+    /** Price the mandate must authorize, in minor units of `currency`. */
+    amount: number;
+    currency: string;
+}
+export interface GateResult {
+    /** True iff the presented mandate authorizes this payment to this counterparty. */
+    granted: boolean;
+    /** Human-readable failure reasons; empty iff granted. */
+    reasons: string[];
+    /** The principal (sponsor) that signed the mandate — present iff the signature is valid. */
+    principal?: string;
+    /** The agent the mandate authorizes. */
+    agent: string;
+}
+/**
+ * Does `envelope` (plus any prior receipts under it) authorize a payment matching
+ * `requirement` to THIS counterparty? Verifies the mandate's signature, validity window,
+ * revocation, scope (this counterparty + action + per-transaction cap), and remaining
+ * budget. Returns granted + reasons, plus the verified principal/agent for KYA.
+ *
+ * Budget caveat: the rolling-budget check is only sound if `priorReceipts` is the agent's
+ * COMPLETE spend history under this mandate. An isolated counterparty that passes a partial or
+ * empty history is soundly enforcing the per-transaction cap + scope (which don't need history),
+ * but NOT the global rolling budget — the agent controls which receipts it presents. See spec §8.
+ */
+export declare function checkMandate(envelope: Mandate, requirement: ResourceRequirement, priorReceipts?: Receipt[], opts?: VerifyOptions): GateResult;
+//# sourceMappingURL=gate.d.ts.map

package/dist/gate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gate.d.ts","sourceRoot":"","sources":["../src/gate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,EAAa,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5D,OAAO,KAAK,EAAU,OAAO,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAE3D,MAAM,WAAW,mBAAmB;IAClC,+EAA+E;IAC/E,YAAY,EAAE,MAAM,CAAC;IACrB,2EAA2E;IAC3E,MAAM,EAAE,MAAM,CAAC;IACf,sEAAsE;IACtE,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,UAAU;IACzB,mFAAmF;IACnF,OAAO,EAAE,OAAO,CAAC;IACjB,yDAAyD;IACzD,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,4FAA4F;IAC5F,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,wCAAwC;IACxC,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAC1B,QAAQ,EAAE,OAAO,EACjB,WAAW,EAAE,mBAAmB,EAChC,aAAa,GAAE,OAAO,EAAO,EAC7B,IAAI,GAAE,aAAkB,GACvB,UAAU,CAiBZ"}

package/dist/gate.js

@@ -0,0 +1,46 @@
+/**
+ * Gate — the counterparty side.
+ *
+ * The client-side guard (AgentWallet) protects an agent from itself. This is the other
+ * half: a resource server, merchant, paid API, or another agent uses `checkMandate` to
+ * REQUIRE a valid mandate before dealing with an incoming agent — verifying that the
+ * agent's mandate is signed by a real principal and authorizes a payment to *this*
+ * counterparty, within its limits and remaining budget.
+ *
+ * This is what makes a mandate something a counterparty *requires* rather than a
+ * DIY-able self-check: the requirement lives on the receiving side, so an agent can only
+ * transact here by presenting the verifiable artifact. Nothing an agent codes on its own
+ * side satisfies a counterparty that demands a signed mandate.
+ */
+import { authorize } from "./verify.js";
+import { verifyMandateSignature } from "./envelope.js";
+/**
+ * Does `envelope` (plus any prior receipts under it) authorize a payment matching
+ * `requirement` to THIS counterparty? Verifies the mandate's signature, validity window,
+ * revocation, scope (this counterparty + action + per-transaction cap), and remaining
+ * budget. Returns granted + reasons, plus the verified principal/agent for KYA.
+ *
+ * Budget caveat: the rolling-budget check is only sound if `priorReceipts` is the agent's
+ * COMPLETE spend history under this mandate. An isolated counterparty that passes a partial or
+ * empty history is soundly enforcing the per-transaction cap + scope (which don't need history),
+ * but NOT the global rolling budget — the agent controls which receipts it presents. See spec §8.
+ */
+export function checkMandate(envelope, requirement, priorReceipts = [], opts = {}) {
+    const candidate = {
+        type: requirement.action,
+        counterparty: requirement.counterparty,
+        amount: requirement.amount,
+        currency: requirement.currency,
+    };
+    // `authorize` checks: envelope signature, validity window, revocation, the chain,
+    // the candidate's scope (action/counterparty/per-txn cap), and budget incl. candidate.
+    const verdict = authorize(envelope, priorReceipts, candidate, opts);
+    const sigOk = verifyMandateSignature(envelope);
+    return {
+        granted: verdict.ok,
+        reasons: verdict.reasons,
+        ...(sigOk ? { principal: envelope.principal } : {}),
+        agent: envelope.agent,
+    };
+}
+//# sourceMappingURL=gate.js.map

package/dist/gate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gate.js","sourceRoot":"","sources":["../src/gate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,EAAE,SAAS,EAAsB,MAAM,aAAa,CAAC;AAC5D,OAAO,EAAE,sBAAsB,EAAE,MAAM,eAAe,CAAC;AAwBvD;;;;;;;;;;GAUG;AACH,MAAM,UAAU,YAAY,CAC1B,QAAiB,EACjB,WAAgC,EAChC,gBAA2B,EAAE,EAC7B,OAAsB,EAAE;IAExB,MAAM,SAAS,GAAW;QACxB,IAAI,EAAE,WAAW,CAAC,MAAM;QACxB,YAAY,EAAE,WAAW,CAAC,YAAY;QACtC,MAAM,EAAE,WAAW,CAAC,MAAM;QAC1B,QAAQ,EAAE,WAAW,CAAC,QAAQ;KAC/B,CAAC;IACF,kFAAkF;IAClF,uFAAuF;IACvF,MAAM,OAAO,GAAG,SAAS,CAAC,QAAQ,EAAE,aAAa,EAAE,SAAS,EAAE,IAAI,CAAC,CAAC;IACpE,MAAM,KAAK,GAAG,sBAAsB,CAAC,QAAQ,CAAC,CAAC;IAC/C,OAAO;QACL,OAAO,EAAE,OAAO,CAAC,EAAE;QACnB,OAAO,EAAE,OAAO,CAAC,OAAO;QACxB,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,QAAQ,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACnD,KAAK,EAAE,QAAQ,CAAC,KAAK;KACtB,CAAC;AACJ,CAAC"}

package/dist/guard.d.ts

@@ -0,0 +1,53 @@
+import type { Action, Mandate, Outcome, Receipt, Verdict } from "./types.js";
+/** Thrown when the mandate blocks an action before any money moves. */
+export declare class GuardViolation extends Error {
+    readonly reasons: string[];
+    readonly action: Action;
+    constructor(action: Action, reasons: string[]);
+}
+/**
+ * The developer's executor: the real side-effect (charge a card, submit an x402 payment,
+ * call a purchase tool). Returns the settled/failed outcome and any result payload.
+ * The guard only calls this if the action is authorized.
+ */
+export type SpendExecutor<T> = (action: Action) => Promise<{
+    outcome: Outcome;
+    result?: T;
+}> | {
+    outcome: Outcome;
+    result?: T;
+};
+export interface AgentWalletOptions {
+    /** Override the clock (testing/determinism). */
+    now?: () => Date;
+    /** Optional sink for signed receipts — e.g. POST them to a hosted verifier (network value). */
+    onReceipt?: (receipt: Receipt) => void;
+    /** Optional hook fired when an action is blocked (telemetry, alerting). */
+    onViolation?: (violation: GuardViolation) => void;
+}
+/**
+ * Wraps an envelope + the agent's key and enforces it locally around every spend.
+ * Holds the local receipt chain so budgets accumulate correctly across a session.
+ */
+export declare class AgentWallet {
+    private readonly envelope;
+    private readonly agentPrivateKeyPem;
+    private readonly options;
+    private chain;
+    constructor(envelope: Mandate, agentPrivateKeyPem: string, options?: AgentWalletOptions);
+    private now;
+    /** The signed receipt chain accumulated so far (read-only). */
+    get receipts(): readonly Receipt[];
+    /** Check whether an action WOULD be allowed, without executing or recording anything. */
+    preauthorize(action: Action): Verdict;
+    /**
+     * The guarded spend. Runs the mandate check FIRST; only if it passes is `executor`
+     * invoked (the point at which real money moves). Records a signed receipt for the
+     * outcome. Throws GuardViolation — before any side effect — if the action is out of scope.
+     */
+    spend<T>(action: Action, executor: SpendExecutor<T>): Promise<{
+        receipt: Receipt;
+        result?: T;
+    }>;
+}
+//# sourceMappingURL=guard.d.ts.map

package/dist/guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guard.d.ts","sourceRoot":"","sources":["../src/guard.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAE7E,uEAAuE;AACvE,qBAAa,cAAe,SAAQ,KAAK;IACvC,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBACZ,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE;CAM9C;AAED;;;;GAIG;AACH,MAAM,MAAM,aAAa,CAAC,CAAC,IAAI,CAC7B,MAAM,EAAE,MAAM,KACX,OAAO,CAAC;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,CAAC,CAAA;CAAE,CAAC,GAAG;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,CAAC,CAAA;CAAE,CAAC;AAElF,MAAM,WAAW,kBAAkB;IACjC,gDAAgD;IAChD,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;IACjB,+FAA+F;IAC/F,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,CAAC;IACvC,2EAA2E;IAC3E,WAAW,CAAC,EAAE,CAAC,SAAS,EAAE,cAAc,KAAK,IAAI,CAAC;CACnD;AAED;;;GAGG;AACH,qBAAa,WAAW;IAGpB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,kBAAkB;IACnC,OAAO,CAAC,QAAQ,CAAC,OAAO;IAJ1B,OAAO,CAAC,KAAK,CAAiB;gBAEX,QAAQ,EAAE,OAAO,EACjB,kBAAkB,EAAE,MAAM,EAC1B,OAAO,GAAE,kBAAuB;IAGnD,OAAO,CAAC,GAAG;IAIX,+DAA+D;IAC/D,IAAI,QAAQ,IAAI,SAAS,OAAO,EAAE,CAEjC;IAED,yFAAyF;IACzF,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO;IAIrC;;;;OAIG;IACG,KAAK,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,CAAC,CAAA;KAAE,CAAC;CAsBtG"}

package/dist/guard.js

@@ -0,0 +1,76 @@
+/**
+ * Guard — a client-side spending firewall around an agent's own money-moving actions.
+ *
+ * This protects the developer's own agent from itself (bugs, hallucinations, prompt
+ * injection). The guard check runs BEFORE the executor, so a compromised agent cannot
+ * execute an out-of-scope payment. Every allowed action still emits a signed receipt —
+ * a tamper-proof audit trail.
+ *
+ * A developer installs this because they do not want their agent tricked into wiring funds
+ * to an attacker — a documented, actively-exploited failure mode.
+ */
+import { authorize } from "./verify.js";
+import { issueReceipt, nextPrevHash } from "./receipt.js";
+/** Thrown when the mandate blocks an action before any money moves. */
+export class GuardViolation extends Error {
+    reasons;
+    action;
+    constructor(action, reasons) {
+        super(`mandate blocked action: ${reasons.join("; ")}`);
+        this.name = "GuardViolation";
+        this.reasons = reasons;
+        this.action = action;
+    }
+}
+/**
+ * Wraps an envelope + the agent's key and enforces it locally around every spend.
+ * Holds the local receipt chain so budgets accumulate correctly across a session.
+ */
+export class AgentWallet {
+    envelope;
+    agentPrivateKeyPem;
+    options;
+    chain = [];
+    constructor(envelope, agentPrivateKeyPem, options = {}) {
+        this.envelope = envelope;
+        this.agentPrivateKeyPem = agentPrivateKeyPem;
+        this.options = options;
+    }
+    now() {
+        return this.options.now?.() ?? new Date();
+    }
+    /** The signed receipt chain accumulated so far (read-only). */
+    get receipts() {
+        return this.chain;
+    }
+    /** Check whether an action WOULD be allowed, without executing or recording anything. */
+    preauthorize(action) {
+        return authorize(this.envelope, this.chain, action, { now: this.now() });
+    }
+    /**
+     * The guarded spend. Runs the mandate check FIRST; only if it passes is `executor`
+     * invoked (the point at which real money moves). Records a signed receipt for the
+     * outcome. Throws GuardViolation — before any side effect — if the action is out of scope.
+     */
+    async spend(action, executor) {
+        const verdict = this.preauthorize(action);
+        if (!verdict.ok) {
+            const violation = new GuardViolation(action, verdict.reasons);
+            this.options.onViolation?.(violation);
+            throw violation; // executor is NEVER called — the firewall property
+        }
+        const { outcome, result } = await executor(action);
+        const receipt = issueReceipt({
+            envelope: this.envelope,
+            agentPrivateKeyPem: this.agentPrivateKeyPem,
+            action,
+            prevReceiptHash: nextPrevHash(this.chain),
+            outcome,
+            now: this.now(),
+        });
+        this.chain.push(receipt);
+        this.options.onReceipt?.(receipt);
+        return { receipt, result };
+    }
+}
+//# sourceMappingURL=guard.js.map

package/dist/guard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"guard.js","sourceRoot":"","sources":["../src/guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAG1D,uEAAuE;AACvE,MAAM,OAAO,cAAe,SAAQ,KAAK;IAC9B,OAAO,CAAW;IAClB,MAAM,CAAS;IACxB,YAAY,MAAc,EAAE,OAAiB;QAC3C,KAAK,CAAC,2BAA2B,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACvD,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC;QAC7B,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;CACF;AAoBD;;;GAGG;AACH,MAAM,OAAO,WAAW;IAGH;IACA;IACA;IAJX,KAAK,GAAc,EAAE,CAAC;IAC9B,YACmB,QAAiB,EACjB,kBAA0B,EAC1B,UAA8B,EAAE;QAFhC,aAAQ,GAAR,QAAQ,CAAS;QACjB,uBAAkB,GAAlB,kBAAkB,CAAQ;QAC1B,YAAO,GAAP,OAAO,CAAyB;IAChD,CAAC;IAEI,GAAG;QACT,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,IAAI,IAAI,IAAI,EAAE,CAAC;IAC5C,CAAC;IAED,+DAA+D;IAC/D,IAAI,QAAQ;QACV,OAAO,IAAI,CAAC,KAAK,CAAC;IACpB,CAAC;IAED,yFAAyF;IACzF,YAAY,CAAC,MAAc;QACzB,OAAO,SAAS,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;IAC3E,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,KAAK,CAAI,MAAc,EAAE,QAA0B;QACvD,MAAM,OAAO,GAAG,IAAI,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC;QAC1C,IAAI,CAAC,OAAO,CAAC,EAAE,EAAE,CAAC;YAChB,MAAM,SAAS,GAAG,IAAI,cAAc,CAAC,MAAM,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC;YAC9D,IAAI,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC,SAAS,CAAC,CAAC;YACtC,MAAM,SAAS,CAAC,CAAC,mDAAmD;QACtE,CAAC;QAED,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,MAAM,QAAQ,CAAC,MAAM,CAAC,CAAC;QAEnD,MAAM,OAAO,GAAG,YAAY,CAAC;YAC3B,QAAQ,EAAE,IAAI,CAAC,QAAQ;YACvB,kBAAkB,EAAE,IAAI,CAAC,kBAAkB;YAC3C,MAAM;YACN,eAAe,EAAE,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC;YACzC,OAAO;YACP,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE;SAChB,CAAC,CAAC;QACH,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACzB,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,CAAC,OAAO,CAAC,CAAC;QAClC,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC;IAC7B,CAAC;CACF"}