@vantic/sdk 0.1.0

package/dist/verify.js

@@ -0,0 +1,124 @@
+/**
+ * Verification & authorization — the core of the protocol (spec §6).
+ *
+ * `verifyChain` validates an envelope + its full receipt history (the dispute-evidence
+ * path). `authorize` checks a candidate action *before* it happens (the gateway path).
+ */
+import { mandateHash, verifyMandateSignature } from "./envelope.js";
+import { receiptHash, verifyReceiptSignature } from "./receipt.js";
+/** Counterparty matcher: exact match or leading-wildcard domain suffix (`*.shop.example`). */
+export function counterpartyAllowed(allowed, counterparty) {
+    if (!allowed || allowed.length === 0)
+        return true; // unconstrained
+    return allowed.some((pattern) => {
+        if (pattern === "*")
+            return true;
+        if (pattern.startsWith("*.")) {
+            const suffix = pattern.slice(1); // ".shop.example"
+            return counterparty.endsWith(suffix) && counterparty.length > suffix.length;
+        }
+        return pattern === counterparty;
+    });
+}
+/** Check a single action against the static scope rules (type / counterparty / per-txn cap). */
+function scopeViolations(scope, action, label) {
+    const reasons = [];
+    if (scope.allowedActions && !scope.allowedActions.includes(action.type)) {
+        reasons.push(`${label}: action '${action.type}' not in allowedActions`);
+    }
+    if (!counterpartyAllowed(scope.allowedCounterparties, action.counterparty)) {
+        reasons.push(`${label}: counterparty '${action.counterparty}' not allowed`);
+    }
+    if (scope.maxPerTransaction != null && action.amount > scope.maxPerTransaction) {
+        reasons.push(`${label}: amount ${action.amount} exceeds maxPerTransaction ${scope.maxPerTransaction}`);
+    }
+    if (scope.budget && action.currency !== scope.budget.currency) {
+        reasons.push(`${label}: currency '${action.currency}' differs from budget currency '${scope.budget.currency}'`);
+    }
+    return reasons;
+}
+/** Sum non-failed spend within the budget window ending at `now`. */
+function spendInWindow(scope, receipts, now) {
+    if (!scope.budget)
+        return 0;
+    const cutoff = now.getTime() - scope.budget.windowSeconds * 1000;
+    return receipts
+        .filter((r) => r.outcome !== "failed" && new Date(r.timestamp).getTime() >= cutoff)
+        .reduce((sum, r) => sum + r.action.amount, 0);
+}
+/** Validate envelope alone (signature, validity window, revocation). */
+function envelopeReasons(env, opts) {
+    const now = opts.now ?? new Date();
+    const skew = (opts.clockSkewSeconds ?? 0) * 1000;
+    const reasons = [];
+    if (!verifyMandateSignature(env))
+        reasons.push("mandate: signature invalid or not signed by principal");
+    const start = new Date(env.issuedAt).getTime();
+    const end = new Date(env.expiresAt).getTime();
+    const t = now.getTime();
+    if (t < start - skew)
+        reasons.push("mandate: not yet valid (issuedAt in the future)");
+    if (t >= end + skew)
+        reasons.push("mandate: expired");
+    if (opts.isRevoked?.(env))
+        reasons.push("mandate: revoked");
+    return reasons;
+}
+/**
+ * Full verification of an envelope and its ordered receipt chain (spec §6).
+ * This is what a verifier runs on a dispute-evidence bundle.
+ */
+export function verifyChain(env, receipts, opts = {}) {
+    const now = opts.now ?? new Date();
+    const reasons = envelopeReasons(env, opts);
+    const eHash = mandateHash(env);
+    let prevHash = null;
+    receipts.forEach((r, i) => {
+        const label = `receipt[${i}]`;
+        if (r.mandateId !== env.id)
+            reasons.push(`${label}: mandateId does not match mandate`);
+        if (r.mandateHash !== eHash)
+            reasons.push(`${label}: mandateHash mismatch (mandate was altered)`);
+        if (r.agent !== env.agent)
+            reasons.push(`${label}: agent does not match mandate`);
+        if (!verifyReceiptSignature(r))
+            reasons.push(`${label}: signature invalid or not signed by agent`);
+        if ((r.prevReceiptHash ?? null) !== prevHash)
+            reasons.push(`${label}: chain broken (prevReceiptHash mismatch)`);
+        reasons.push(...scopeViolations(env.scope, r.action, label));
+        prevHash = receiptHash(r);
+    });
+    let cumulativeSpend;
+    if (env.scope.budget) {
+        cumulativeSpend = spendInWindow(env.scope, receipts, now);
+        if (cumulativeSpend > env.scope.budget.amount) {
+            reasons.push(`budget exceeded: ${cumulativeSpend} > ${env.scope.budget.amount} ${env.scope.budget.currency} within ${env.scope.budget.windowSeconds}s window`);
+        }
+    }
+    return { ok: reasons.length === 0, reasons, cumulativeSpend };
+}
+/**
+ * Pre-transaction authorization (the gateway path). Given the envelope, the prior
+ * receipt chain, and a candidate action, decide whether the agent may proceed.
+ * Validates the envelope, the existing chain, the candidate's static scope, and the
+ * budget *including* the candidate.
+ */
+export function authorize(env, priorReceipts, candidate, opts = {}) {
+    const now = opts.now ?? new Date();
+    // The existing state must itself be valid.
+    const base = verifyChain(env, priorReceipts, opts);
+    const reasons = [...base.reasons];
+    // Candidate's static scope.
+    reasons.push(...scopeViolations(env.scope, candidate, "candidate"));
+    // Budget including the candidate.
+    let cumulativeSpend = base.cumulativeSpend ?? 0;
+    if (env.scope.budget) {
+        const projected = spendInWindow(env.scope, priorReceipts, now) + candidate.amount;
+        cumulativeSpend = projected;
+        if (projected > env.scope.budget.amount) {
+            reasons.push(`candidate would exceed budget: ${projected} > ${env.scope.budget.amount} ${env.scope.budget.currency}`);
+        }
+    }
+    return { ok: reasons.length === 0, reasons, cumulativeSpend };
+}
+//# sourceMappingURL=verify.js.map

package/dist/verify.js.map

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

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@vantic/sdk",
+  "version": "0.1.0",
+  "description": "Vantic — a spending firewall and permission layer for AI agents: signed mandates, allowlists, and tamper-proof receipts for every money-moving action.",
+  "type": "module",
+  "license": "Apache-2.0",
+  "author": "Vantic Labs",
+  "engines": { "node": ">=18" },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": { "vantic-mcp": "dist/mcp.js" },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": ["dist/*.js", "dist/*.d.ts", "dist/*.d.ts.map", "dist/*.js.map", "!dist/demo.*", "!dist/*-demo.*", "README.md", "LICENSE"],
+  "publishConfig": { "access": "public" },
+  "repository": { "type": "git", "url": "git+https://github.com/vanticlabs/vantic.git" },
+  "homepage": "https://github.com/vanticlabs/vantic#readme",
+  "bugs": { "url": "https://github.com/vanticlabs/vantic/issues" },
+  "scripts": {
+    "build": "tsc",
+    "test": "node --test dist/test/",
+    "demo": "tsc && node dist/demo.js",
+    "guard-demo": "tsc && node dist/guard-demo.js",
+    "adapters-demo": "tsc && node dist/adapters-demo.js",
+    "identity-demo": "tsc && node dist/identity-demo.js",
+    "gate-demo": "tsc && node dist/gate-demo.js",
+    "mcp": "tsc && node dist/mcp.js",
+    "prepublishOnly": "tsc"
+  },
+  "keywords": ["ai-agents", "agentic-commerce", "delegation", "ed25519", "receipts", "mcp", "mcp-server", "did", "verifiable-credentials", "agent-payments", "prompt-injection"],
+  "devDependencies": {
+    "typescript": "^5.5.0",
+    "@types/node": "^20.0.0"
+  }
+}