@decidio/sdk 0.1.7 → 0.1.9

package/dist/signing.js

@@ -1,4 +1,13 @@
+// Client-side agent identity (§13 P0-8). The agent generates its Ed25519 keypair LOCALLY
+// (the private key never crosses the wire — `init` registers only the public did:key) and
+// signs a REQUEST-BOUND proof on each authorize: a detached Ed25519 JWS over
+// canonical({agentId,did,action,amount,scope,nonce,exp}). Decidio's floor verifies the
+// signature, binds it to the exact request, burns the single-use nonce, and checks the
+// did against the agent registry — so the gate PROVES who is calling instead of trusting a
+// label. This canonicalize + proof shape is byte-identical to apps/api (canonical.ts +
+// a2a/identity.ts), so a proof signed here verifies there.
 import { generateKeyPairSync, createPrivateKey, sign as edSign, randomUUID } from "node:crypto";
+// base58btc (Bitcoin alphabet) — for the did:key multibase 'z' prefix.
 const B58 = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz";
 function b58encode(buf) {
     const digits = [0];
@@ -25,6 +34,7 @@ function b58encode(buf) {
         str += B58[digits[i]];
     return str;
 }
+/** Sorted-key JCS — must match apps/api/src/canonical.ts byte-for-byte. */
 export function canonicalize(v) {
     if (v === null || typeof v !== "object")
         return JSON.stringify(v);
@@ -33,6 +43,9 @@ export function canonicalize(v) {
     const o = v;
     return `{${Object.keys(o).sort().map((k) => `${JSON.stringify(k)}:${canonicalize(o[k])}`).join(",")}}`;
 }
+/** Generate a fresh Ed25519 keypair LOCALLY. Returns the public `did:key` (register this)
+ *  and the PKCS8 private key base64 (keep this in the agent host's env as DECIDIO_AGENT_KEY —
+ *  it never goes back to Decidio). */
 export function generateKeypair() {
     const { privateKey, publicKey } = generateKeyPairSync("ed25519");
     const jwk = publicKey.export({ format: "jwk" });
@@ -41,18 +54,78 @@ export function generateKeypair() {
     const privateKeyBase64 = privateKey.export({ format: "der", type: "pkcs8" }).toString("base64");
     return { did, privateKeyBase64 };
 }
+/** Sign the CONFIRM call (bound to {action:"confirm", scope:decisionId}) so the gate can
+ *  prove the caller is the receipt's original requester before granting the wrapper tier
+ *  (application_confirmed). Returns undefined when no signing key is configured (the server
+ *  then caps the report at agent_asserted). Used by EVERY confirm path — inline, durable
+ *  resume, and the engine adapters — so the production paths confirm with a proof too. Also
+ *  binds `workspaceId` (D-B3.6) when configured, so the confirm proof is tenant-scoped too. */
 export function signConfirm(decisionId, cfg) {
     if (!cfg.agentKey || !cfg.agentDid || !cfg.agentId)
         return undefined;
     return signBoundProof(cfg.agentKey, { agentId: cfg.agentId, did: cfg.agentDid, action: "confirm", amount: 0, scope: decisionId, workspaceId: cfg.workspaceId });
 }
+/** Sign a request-bound identity proof. The returned object is sent verbatim as the
+ *  `requesterIdentity` field of /agent/authorize. */
 export function signBoundProof(privateKeyBase64, fields) {
     const key = createPrivateKey({ key: Buffer.from(privateKeyBase64, "base64"), format: "der", type: "pkcs8" });
     const nonce = fields.nonce ?? randomUUID();
     const exp = (fields.now ?? Date.now()) + (fields.ttlMs ?? 120_000);
+    // OMIT scope/workspaceId when absent so the canonical bytes match the server + the Python SDK — a key
+    // with an undefined value would serialize as literal "undefined", which Python can't reproduce, and a
+    // legacy (no-workspace) proof must stay byte-identical. The server's bound-payload reconstruction
+    // omits them the same way (a2a/identity.ts).
     const payloadObj = { agentId: fields.agentId, did: fields.did, action: fields.action, amount: fields.amount, ...(fields.scope !== undefined ? { scope: fields.scope } : {}), ...(fields.workspaceId !== undefined ? { workspaceId: fields.workspaceId } : {}), nonce, exp };
     const payload = Buffer.from(canonicalize(payloadObj), "utf8").toString("base64url");
     const protectedHdr = Buffer.from(JSON.stringify({ alg: "EdDSA", kid: fields.did }), "utf8").toString("base64url");
     const signature = Buffer.from(edSign(null, Buffer.from(`${protectedHdr}.${payload}`, "utf8"), key)).toString("base64url");
     return { agentId: fields.agentId, did: fields.did, action: fields.action, amount: fields.amount, scope: fields.scope, workspaceId: fields.workspaceId, nonce, exp, proof: { protected: protectedHdr, signature } };
 }
+/** The values that do not survive `JSON.stringify → JSON.parse` with their meaning intact.
+ *  Refused at the GATE, before anything is routed, signed, or parked (prodsec F-01: `NaN`
+ *  canonicalized to `null` and a `Map` to `{}`, so the integrity signature matched the drifted
+ *  bytes and the function EXECUTED with arguments that meant something else — the exact wrong
+ *  execution the parked-payload signature exists to refuse). Throws naming the offending path;
+ *  returns nothing. The supported data model is plain JSON: null, boolean, string, finite
+ *  number, plain array, plain object. */
+export function assertJsonSafe(value, path = "args") {
+    const seen = new Set();
+    const walk = (v, p) => {
+        if (v === null || typeof v === "boolean" || typeof v === "string")
+            return;
+        if (typeof v === "number") {
+            if (!Number.isFinite(v))
+                throw new Error(`[decidio] ${p} is ${String(v)} — a non-finite number does not survive JSON (it becomes null), so what a human approves would not be what executes. The decision was NOT routed; pass a finite number or a string.`);
+            return;
+        }
+        if (typeof v === "undefined")
+            throw new Error(`[decidio] ${p} is undefined — JSON drops or nullifies it, so what a human approves would not be what executes. The decision was NOT routed; use null explicitly or omit the field.`);
+        if (typeof v === "bigint")
+            throw new Error(`[decidio] ${p} is a BigInt — JSON cannot represent it. The decision was NOT routed; pass it as a string.`);
+        if (typeof v === "function" || typeof v === "symbol")
+            throw new Error(`[decidio] ${p} is a ${typeof v} — it cannot be serialized for approval. The decision was NOT routed.`);
+        if (typeof v === "object") {
+            if (seen.has(v))
+                throw new Error(`[decidio] ${p} is part of a circular structure — it cannot be serialized for approval. The decision was NOT routed.`);
+            seen.add(v);
+            if (Array.isArray(v)) {
+                v.forEach((x, i) => walk(x, `${p}[${i}]`));
+                seen.delete(v);
+                return;
+            }
+            const proto = Object.getPrototypeOf(v);
+            if (proto !== Object.prototype && proto !== null) {
+                const name = v?.constructor?.name ?? "a class instance";
+                throw new Error(`[decidio] ${p} is ${name === "Object" ? "an exotic object" : `a ${name}`} — only plain JSON objects survive serialization with their meaning intact (a Map, for example, becomes {}). The decision was NOT routed; convert it to plain JSON first.`);
+            }
+            if (typeof v.toJSON === "function")
+                throw new Error(`[decidio] ${p} defines toJSON() — its serialized form would differ from the value the signature covers. The decision was NOT routed; pass the plain serialized form instead.`);
+            for (const [k, x] of Object.entries(v))
+                walk(x, `${p}.${k}`);
+            seen.delete(v);
+            return;
+        }
+        throw new Error(`[decidio] ${p} has unsupported type ${typeof v}. The decision was NOT routed.`);
+    };
+    walk(value, path);
+}

package/openapi.yaml

@@ -5,7 +5,7 @@
 openapi: 3.1.0
 info:
   title: Decidio Agent Gate
-  version: 0.1.7
+  version: 0.1.9
   description: >
     Authorize an AI-agent action (proceed | route | block), confirm the captured outcome, and
     receive the signed resume webhook when a routed action is decided. Every outcome seals a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decidio/sdk",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "description": "One-line approval gate for AI-agent actions. Wrap a risky tool call with guard.protect(); Decidio's policy engine decides proceed | route | block, a human approves routed actions, and every outcome is sealed as a verifiable Authority Receipt.",
   "license": "Apache-2.0",
   "type": "module",
@@ -81,10 +81,16 @@
     "prepublishOnly": "npm run typecheck && npm run build"
   },
   "dependencies": {
-    "@decidio/verify": "^0.1.3"
+    "@decidio/verify": "0.1.8"
   },
   "author": "OmniTwin Technologies Inc.",
   "bugs": {
     "url": "https://decidioai.com/support/"
+  },
+  "peerDependencies": {
+    "inngest": ">=3 <4",
+    "@langchain/langgraph": ">=0.2 <2",
+    "@temporalio/workflow": ">=1 <2",
+    "@openai/agents": ">=0.0.1 <2"
   }
 }