@ixo/flow-work 0.2.0 → 0.4.1

package/dist/protocol.js

@@ -1,23 +1,172 @@
+import { createHash } from 'node:crypto';
 import { z } from 'zod';
-/**
- * The flow-work wire protocol — the Matrix events flow-manager and helper
- * oracles exchange. Mirror of flow-manager's oracle-delegation plugin
- * (apps/app/src/plugins/oracle-delegation/oracle-room.ts). If these shapes
- * change, both sides change together; until this lives in a shared package
- * the duplication is deliberate and must be kept in sync.
- */
+/** Matrix event names for flow-work protocol v2. */
 export const FLOW_WORK_ASSIGN_EVENT = 'ixo.flow.work.assign';
+export const FLOW_WORK_READY_EVENT = 'ixo.flow.work.ready';
 export const FLOW_WORK_INVOKE_EVENT = 'ixo.flow.work.invoke';
 export const FLOW_WORK_RECEIPT_EVENT = 'ixo.flow.work.receipt';
-export const flowWorkInvokeSchema = z.object({
-    invocationId: z.string().trim().min(1),
-    capability: z.string().trim().min(1),
-    actionType: z.string().trim().min(1),
-    nodeId: z.string().trim().min(1),
+const nonEmpty = z.string().trim().min(1);
+const reservedNbKeys = new Set([
+    'protocolVersion',
+    'invocationId',
+    'managerDid',
+    'audience',
+    'actionType',
+    'nodeId',
+    'inputHash',
+    'attempt',
+    'deadline',
+    'delegationDepth',
+]);
+const contractCaveatsSchema = z
+    .record(z.string(), z.unknown())
+    .refine((value) => Object.keys(value).every((key) => !reservedNbKeys.has(key)), 'contractCaveats cannot override flow-work protocol bindings');
+const bindingShape = {
+    protocolVersion: z.literal(2),
+    invocationId: nonEmpty,
+    managerDid: nonEmpty,
+    /** Entity DID of the oracle contracted for this invocation. */
+    audience: nonEmpty,
+    capability: nonEmpty,
+    actionType: nonEmpty,
+    nodeId: nonEmpty,
+    /** UCAN resource, and therefore the exact value of capability.with. */
+    resource: nonEmpty,
+    inputHash: z.string().regex(/^sha256:[0-9a-f]{64}$/),
+    attempt: z.number().int().safe().min(1),
+    /** Absolute Unix epoch deadline in milliseconds. */
+    deadline: z.number().int().safe().positive(),
+    /** Service-contract caveats copied exactly into the UCAN nb object. */
+    contractCaveats: contractCaveatsSchema,
+};
+/**
+ * Immutable routing and authorization binding shared by assign, ready, invoke,
+ * and receipt. Every hop repeats these fields so no event can be spliced into
+ * a different contract.
+ */
+export const flowWorkBindingSchema = z.object(bindingShape).strict();
+export const flowWorkAssignSchema = z
+    .object({
+    ...bindingShape,
+    /** Exact Matrix operator user id contracted for this entity DID. */
+    oracleMatrixId: nonEmpty,
+    assignedAt: z.string().datetime(),
+    status: z.literal('invited'),
+})
+    .strict();
+export const flowWorkReadySchema = z
+    .object({
+    ...bindingShape,
+    status: z.literal('ready'),
+})
+    .strict();
+export const flowWorkInvokeSchema = z
+    .object({
+    ...bindingShape,
     inputs: z.record(z.string(), z.unknown()),
     /** Serialized UCAN delegation (base64 CAR) authorizing this work. */
-    delegation: z.string().trim().min(1),
-    /** DID of the oracle this invocation is addressed to. */
-    audience: z.string().trim().min(1),
-});
+    delegation: nonEmpty,
+})
+    .strict();
+export const flowWorkErrorCodeSchema = z.enum([
+    'assignment_missing',
+    'sender_untrusted',
+    'binding_mismatch',
+    'deadline_expired',
+    'delegation_invalid',
+    'delegation_expired',
+    'capability_not_declared',
+    'input_invalid',
+    'output_invalid',
+    'tool_error',
+]);
+export const flowWorkReceiptSchema = z.discriminatedUnion('status', [
+    z
+        .object({
+        ...bindingShape,
+        status: z.literal('success'),
+        output: z.record(z.string(), z.unknown()).nullable(),
+        error: z.null(),
+    })
+        .strict(),
+    z
+        .object({
+        ...bindingShape,
+        status: z.literal('failure'),
+        output: z.null(),
+        error: z
+            .object({
+            code: flowWorkErrorCodeSchema,
+            message: z.string(),
+        })
+            .strict(),
+    })
+        .strict(),
+]);
+export function flowWorkNbFor(binding) {
+    return {
+        protocolVersion: binding.protocolVersion,
+        invocationId: binding.invocationId,
+        managerDid: binding.managerDid,
+        audience: binding.audience,
+        actionType: binding.actionType,
+        nodeId: binding.nodeId,
+        inputHash: binding.inputHash,
+        attempt: binding.attempt,
+        deadline: binding.deadline,
+        delegationDepth: 0,
+        ...binding.contractCaveats,
+    };
+}
+export function sameFlowWorkNb(actual, binding) {
+    return (actual !== undefined &&
+        canonicalJson(actual) === canonicalJson(flowWorkNbFor(binding)));
+}
+export const FLOW_WORK_BINDING_FIELDS = [
+    'protocolVersion',
+    'invocationId',
+    'managerDid',
+    'audience',
+    'capability',
+    'actionType',
+    'nodeId',
+    'resource',
+    'inputHash',
+    'attempt',
+    'deadline',
+    'contractCaveats',
+];
+export function sameFlowWorkBinding(left, right) {
+    return FLOW_WORK_BINDING_FIELDS.every((field) => field === 'contractCaveats'
+        ? canonicalJson(left[field]) === canonicalJson(right[field])
+        : left[field] === right[field]);
+}
+/** Stable JSON hash used by assignment to commit to later invoke inputs. */
+export function computeFlowWorkInputHash(inputs) {
+    return `sha256:${createHash('sha256').update(canonicalJson(inputs)).digest('hex')}`;
+}
+export function canonicalJson(value) {
+    if (value === null)
+        return 'null';
+    if (typeof value === 'string' || typeof value === 'boolean') {
+        return JSON.stringify(value);
+    }
+    if (typeof value === 'number') {
+        return Number.isFinite(value) ? JSON.stringify(value) : 'null';
+    }
+    if (Array.isArray(value)) {
+        return `[${value.map((entry) => canonicalJson(entry ?? null)).join(',')}]`;
+    }
+    if (typeof value === 'object') {
+        const record = value;
+        return `{${Object.keys(record)
+            .sort()
+            .filter((key) => record[key] !== undefined)
+            .map((key) => `${JSON.stringify(key)}:${canonicalJson(record[key])}`)
+            .join(',')}}`;
+    }
+    if (value === undefined)
+        return 'null';
+    throw new TypeError(`Cannot hash non-JSON input value of type ${typeof value}`);
+}
 //# sourceMappingURL=protocol.js.map

package/dist/protocol.js.map

@@ -1 +1 @@
-{"version":3,"file":"protocol.js","sourceRoot":"","sources":["../src/protocol.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;GAMG;AAEH,MAAM,CAAC,MAAM,sBAAsB,GAAG,sBAAsB,CAAC;AAC7D,MAAM,CAAC,MAAM,sBAAsB,GAAG,sBAAsB,CAAC;AAC7D,MAAM,CAAC,MAAM,uBAAuB,GAAG,uBAAuB,CAAC;AAE/D,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC3C,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACtC,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACpC,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACpC,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAChC,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC;IACzC,qEAAqE;IACrE,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACpC,yDAAyD;IACzD,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;CACnC,CAAC,CAAC"}
+{"version":3,"file":"protocol.js","sourceRoot":"","sources":["../src/protocol.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ixo/flow-work",
-  "version": "0.2.0",
+  "version": "0.4.1",
   "description": "Oracle-side flow-work plugin: accept UCAN-delegated ixo.flow.work invocations from the IXO flow-manager over Matrix and post receipts.",
   "license": "Apache-2.0",
   "type": "module",
@@ -10,6 +10,10 @@
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
+    },
+    "./input": {
+      "types": "./dist/input.d.ts",
+      "import": "./dist/input.js"
     }
   },
   "files": [
@@ -38,7 +42,7 @@
   "devDependencies": {
     "@changesets/cli": "^2.31.0",
     "@ixo/oracle-runtime": "^1.3.4",
-    "@ixo/ucan": "^2.0.0",
+    "@ixo/ucan": "^2.1.0",
     "@nestjs/common": "^11.1.19",
     "@types/node": "^22.10.7",
     "matrix-js-sdk": "^37.11.0",