@decidio/sdk 0.1.9 → 0.1.11

package/dist/signing.js

@@ -1,13 +1,4 @@
-// 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.
+import { generateKeyPairSync, createPrivateKey, createPublicKey, sign as edSign, verify as edVerify, createHash, randomUUID } from "node:crypto";
 const B58 = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz";
 function b58encode(buf) {
     const digits = [0];
@@ -34,7 +25,6 @@ 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);
@@ -43,9 +33,11 @@ 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 didFromPrivateKey(privateKeyBase64) {
+    const priv = createPrivateKey({ key: Buffer.from(privateKeyBase64, "base64"), format: "der", type: "pkcs8" });
+    const jwk = createPublicKey(priv).export({ format: "jwk" });
+    return "did:key:z" + b58encode(Buffer.concat([Buffer.from([0xed, 0x01]), Buffer.from(jwk.x, "base64url")]));
+}
 export function generateKeypair() {
     const { privateKey, publicKey } = generateKeyPairSync("ed25519");
     const jwk = publicKey.export({ format: "jwk" });
@@ -54,40 +46,29 @@ 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 class DecidioUnsafeArgumentsError extends Error {
+    decisionId;
+    constructor(message, decisionId) {
+        super(message);
+        this.decisionId = decisionId;
+        this.name = "DecidioUnsafeArgumentsError";
+    }
+}
 export function assertJsonSafe(value, path = "args") {
     const seen = new Set();
     const walk = (v, p) => {
@@ -95,18 +76,18 @@ export function assertJsonSafe(value, path = "args") {
             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.`);
+                throw new DecidioUnsafeArgumentsError(`[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. 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.`);
+            throw new DecidioUnsafeArgumentsError(`[decidio] ${p} is undefined — JSON drops or nullifies it, so what a human approves would not be what executes. 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.`);
+            throw new DecidioUnsafeArgumentsError(`[decidio] ${p} is a BigInt — JSON cannot represent it. 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.`);
+            throw new DecidioUnsafeArgumentsError(`[decidio] ${p} is a ${typeof v} — it cannot be serialized for approval.`);
         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.`);
+                throw new DecidioUnsafeArgumentsError(`[decidio] ${p} is part of a circular structure — it cannot be serialized for approval.`);
             seen.add(v);
             if (Array.isArray(v)) {
                 v.forEach((x, i) => walk(x, `${p}[${i}]`));
@@ -116,16 +97,101 @@ export function assertJsonSafe(value, path = "args") {
             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.`);
+                throw new DecidioUnsafeArgumentsError(`[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 {}); 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.`);
+                throw new DecidioUnsafeArgumentsError(`[decidio] ${p} defines toJSON() — its serialized form would differ from the value the signature covers. 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.`);
+        throw new DecidioUnsafeArgumentsError(`[decidio] ${p} has unsupported type ${typeof v}.`);
     };
     walk(value, path);
 }
+export function assertSafeTransport(url, hasCredential) {
+    if (!hasCredential)
+        return;
+    if (/^http:\/\//i.test(url) && !/^http:\/\/(localhost|127\.0\.0\.1|\[::1\])([:/]|$)/i.test(url)) {
+        throw new Error(`[decidio] refusing to send credentials over plaintext http to ${url.replace(/^(https?:\/\/[^/]+).*$/i, "$1")} — use https, or localhost for local dev. Nothing was sent.`);
+    }
+}
+export function signExecutionReport(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 ?? 300_000);
+    const body = {
+        v: 1,
+        purpose: "decidio.execution-report",
+        decisionId: fields.decisionId,
+        agentId: fields.agentId,
+        did: fields.did,
+        ...(fields.workspaceId !== undefined ? { workspaceId: fields.workspaceId } : {}),
+        source: fields.source,
+        resultDigest: fields.resultDigest,
+        digestAlg: "sha-256",
+        canonicalization: "decidio-jcs-1",
+        nonce,
+        exp,
+    };
+    const payload = Buffer.from(canonicalize(body), "utf8").toString("base64url");
+    const protectedHdr = Buffer.from(JSON.stringify({ alg: "EdDSA", kid: fields.did, typ: "decidio-execution-report+jws" }), "utf8").toString("base64url");
+    const signature = Buffer.from(edSign(null, Buffer.from(`${protectedHdr}.${payload}`, "utf8"), key)).toString("base64url");
+    return { ...body, proof: { protected: protectedHdr, signature } };
+}
+export function verifyExecutionReport(report, expect) {
+    const r = report;
+    if (!r || r.purpose !== "decidio.execution-report" || r.v !== 1)
+        return { valid: false, reason: "not a v1 decidio execution report" };
+    if (r.decisionId !== expect.decisionId)
+        return { valid: false, reason: "report is bound to a DIFFERENT decision" };
+    if (expect.did && r.did !== expect.did)
+        return { valid: false, reason: "report was signed by a different agent key" };
+    if (typeof r.exp !== "number" || (expect.now ?? Date.now()) > r.exp)
+        return { valid: false, reason: "report expired" };
+    if (r.digestAlg !== "sha-256" || r.canonicalization !== "decidio-jcs-1")
+        return { valid: false, reason: "unsupported digest/canonicalization" };
+    try {
+        const { proof, ...body } = r;
+        const payload = Buffer.from(canonicalize(body), "utf8").toString("base64url");
+        const mc = b58decode(String(r.did).slice("did:key:z".length));
+        if (mc[0] !== 0xed || mc[1] !== 0x01)
+            return { valid: false, reason: "issuer did is not Ed25519" };
+        const pub = createPublicKey({ key: { kty: "OKP", crv: "Ed25519", x: Buffer.from(mc.subarray(2)).toString("base64url") }, format: "jwk" });
+        const ok = edVerify(null, Buffer.from(`${proof.protected}.${payload}`, "utf8"), pub, Buffer.from(proof.signature, "base64url"));
+        return ok ? { valid: true } : { valid: false, reason: "signature does not verify against the agent did" };
+    }
+    catch (e) {
+        return { valid: false, reason: `malformed report (${e?.message ?? e})` };
+    }
+}
+export function resultDigest(canonicalValue) {
+    return createHash("sha256").update(canonicalize(canonicalValue), "utf8").digest("hex");
+}
+function b58decode(s) {
+    const A = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz";
+    const bytes = [0];
+    for (const ch of s) {
+        const val = A.indexOf(ch);
+        if (val < 0)
+            throw new Error("bad base58 character");
+        let carry = val;
+        for (let i = 0; i < bytes.length; i++) {
+            carry += bytes[i] * 58;
+            bytes[i] = carry & 0xff;
+            carry >>= 8;
+        }
+        while (carry) {
+            bytes.push(carry & 0xff);
+            carry >>= 8;
+        }
+    }
+    for (const ch of s) {
+        if (ch === A[0])
+            bytes.push(0);
+        else
+            break;
+    }
+    return Buffer.from(bytes.reverse());
+}

package/openapi.yaml

@@ -5,7 +5,7 @@
 openapi: 3.1.0
 info:
   title: Decidio Agent Gate
-  version: 0.1.9
+  version: 0.1.11
   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
@@ -101,6 +101,52 @@ components:
         requesterIdentity:
           $ref: "#/components/schemas/RequesterIdentity"
           description: confirm proof is bound to {action:"confirm", scope:decisionId}
+        executionReport:
+          $ref: "#/components/schemas/ExecutionReport"
+    ExecutionReport:
+      type: object
+      description: >
+        OPTIONAL proof of WHAT was executed: a domain-separated, versioned envelope over a digest
+        of the captured response, bound to the decision, the agent and the workspace. The server
+        VERIFIES it before persisting anything — it recomputes the digest from `capturedResponse`
+        on this same request, requires the signer to be the decision's original requesting agent
+        AND still registered and active, and burns the nonce so a report is single-use. A report
+        copied onto a different decision, a different agent, or an altered response is refused.
+
+        A REFUSED REPORT DOES NOT FAIL THE CONFIRM. This envelope grants no authority — the
+        evidence tier comes from the response, the identity from the confirm proof — so an
+        unverifiable attestation is refused as an ATTESTATION (never stored as evidence, and the
+        refusal is itself audited) while the confirmation is still recorded. The response reports
+        which happened via `executionReport.verified`; it is never silent. Omit the field entirely
+        and confirm behaves exactly as before.
+      required: [v, purpose, decisionId, agentId, did, source, resultDigest, digestAlg, canonicalization, nonce, exp, proof]
+      properties:
+        v: { type: integer, enum: [1] }
+        purpose: { type: string, enum: ["decidio.execution-report"], description: domain separation — this signature can never be replayed as another Decidio proof }
+        decisionId: { type: string }
+        agentId: { type: string }
+        did: { type: string, description: "did:key of the signing agent" }
+        workspaceId: { type: string, description: tenant binding; present when the agent knows it }
+        source: { type: string, enum: [wrapper, agent] }
+        resultDigest:
+          type: string
+          pattern: "^[0-9a-f]{64}$"
+          description: lowercase-hex SHA-256 over the canonicalized captured response (the server recomputes it and compares)
+        digestAlg: { type: string, enum: ["sha-256"] }
+        canonicalization: { type: string, enum: ["decidio-jcs-1"], description: RFC 8785 JCS with Decidio's refusal rules }
+        nonce:
+          type: string
+          pattern: "^[A-Za-z0-9._:-]{8,64}$"
+          description: single-use; burned server-side, so a replayed report is refused
+        exp:
+          type: integer
+          description: unix ms expiry. The server also refuses an expiry more than 15 minutes ahead of now — a client-chosen lifetime is not freshness.
+        proof:
+          type: object
+          required: [protected, signature]
+          properties:
+            protected: { type: string, description: "base64url JWS protected header (EdDSA, kid=did, typ=decidio-execution-report+jws)" }
+            signature: { type: string, description: base64url detached signature over protected.payload }
     ResumeWebhook:
       type: object
       description: >

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decidio/sdk",
-  "version": "0.1.9",
+  "version": "0.1.11",
   "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",
@@ -77,20 +77,14 @@
   },
   "scripts": {
     "typecheck": "tsc --noEmit",
-    "build": "node -e \"fs.rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.build.json",
+    "build": "node -e \"fs.rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.build.json && tsc -p tsconfig.types.json",
     "prepublishOnly": "npm run typecheck && npm run build"
   },
   "dependencies": {
-    "@decidio/verify": "0.1.8"
+    "@decidio/verify": "0.1.10"
   },
   "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"
   }
 }