@decidio/sdk 0.1.10 → 0.1.11

package/dist/signing.d.ts

@@ -3,6 +3,10 @@ export declare function canonicalize(v: unknown): string;
 /** 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). */
+/** Derive the public did:key from a stored private key. Lets `doctor` prove that the key on
+ *  this machine is actually the one registered for this agent — a mismatched restore otherwise
+ *  looks healthy until a signed confirmation quietly fails to earn its tier weeks later. */
+export declare function didFromPrivateKey(privateKeyBase64: string): string;
 export declare function generateKeypair(): {
     did: string;
     privateKeyBase64: string;
@@ -64,3 +68,55 @@ export declare function assertJsonSafe(value: unknown, path?: string): void;
  *  session tokens while agent-token requests sailed through). localhost/127.0.0.1/[::1] stay
  *  allowed for local dev; https always allowed. Throws before anything is sent. */
 export declare function assertSafeTransport(url: string, hasCredential: boolean): void;
+/** A signed, DOMAIN-SEPARATED, versioned attestation that THIS agent reported THIS captured
+ *  response for THIS decision. Distinct from the identity proof (`signConfirm`) in every field
+ *  that matters, so a report can never be lifted from one decision onto another: the decision id,
+ *  the workspace, the agent's did, the source, the response digest, the digest algorithm, the
+ *  canonicalization version, a nonce and an expiry are ALL inside the signed bytes.
+ *
+ *  HONEST SCOPE — say this out loud rather than let a reader assume more: this proves integrity
+ *  and agent attribution of the REPORT. It does not prove the downstream system committed
+ *  anything; only the source system can attest that, and the gate's evidence tier is what
+ *  records how strong that attestation is. */
+export interface ExecutionReport {
+    v: 1;
+    purpose: "decidio.execution-report";
+    decisionId: string;
+    agentId: string;
+    did: string;
+    workspaceId?: string;
+    source: string;
+    resultDigest: string;
+    digestAlg: "sha-256";
+    canonicalization: "decidio-jcs-1";
+    nonce: string;
+    exp: number;
+    proof: {
+        protected: string;
+        signature: string;
+    };
+}
+export declare function signExecutionReport(privateKeyBase64: string, fields: {
+    decisionId: string;
+    agentId: string;
+    did: string;
+    workspaceId?: string;
+    source: string;
+    resultDigest: string;
+    ttlMs?: number;
+    now?: number;
+    nonce?: string;
+}): ExecutionReport;
+/** Verify an ExecutionReport LOCALLY — same rules the server applies before persisting it.
+ *  Returns why it failed rather than a bare false, so a caller can say something useful. */
+export declare function verifyExecutionReport(report: unknown, expect: {
+    decisionId: string;
+    did?: string;
+    now?: number;
+}): {
+    valid: boolean;
+    reason?: string;
+};
+/** sha-256 over the canonical JSON of an already-canonical value — the digest an ExecutionReport
+ *  binds. Both languages produce identical bytes for identical values. */
+export declare function resultDigest(canonicalValue: unknown): string;

package/dist/signing.js

@@ -1,4 +1,4 @@
-import { generateKeyPairSync, createPrivateKey, sign as edSign, randomUUID } from "node:crypto";
+import { generateKeyPairSync, createPrivateKey, createPublicKey, sign as edSign, verify as edVerify, createHash, randomUUID } from "node:crypto";
 const B58 = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz";
 function b58encode(buf) {
     const digits = [0];
@@ -33,6 +33,11 @@ export function canonicalize(v) {
     const o = v;
     return `{${Object.keys(o).sort().map((k) => `${JSON.stringify(k)}:${canonicalize(o[k])}`).join(",")}}`;
 }
+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" });
@@ -112,3 +117,81 @@ export function assertSafeTransport(url, hasCredential) {
         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.10
+  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.10",
+  "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",
@@ -81,7 +81,7 @@
     "prepublishOnly": "npm run typecheck && npm run build"
   },
   "dependencies": {
-    "@decidio/verify": "0.1.9"
+    "@decidio/verify": "0.1.10"
   },
   "author": "OmniTwin Technologies Inc.",
   "bugs": {