@openwop/openwop-conformance 1.1.0 → 1.2.0

package/src/scenarios/workflow-chain-pack-signature-verification.test.ts

@@ -0,0 +1,138 @@
+/**
+ * Workflow-chain pack signature verification — `workflow-chain-packs.md`
+ * §"Expansion semantics" step 2 + `node-packs.md` §Signing (reused
+ * verification flow, identical to node packs).
+ *
+ * Server-free scenario. Asserts that the Ed25519 signature verification
+ * recipe from `node-packs.md` §Signing — "`pack.json.sig` is an Ed25519
+ * signature over `pack.json` using the key at `keys/<key-id>.pem`" —
+ * works unchanged for workflow-chain pack manifests. The spec's design
+ * intent is that workflow-chain packs reuse 100% of the node-pack
+ * signing infrastructure (same algorithm, same byte recipe, same key
+ * format); this scenario proves the reuse is real, not just claimed.
+ *
+ * What this scenario covers:
+ *   - A valid (manifest + signature) pair verifies cleanly.
+ *   - A tampered manifest fails verification with the same shape of
+ *     failure as a tampered node pack would produce.
+ *   - A wrong-key signature fails verification.
+ *
+ * Why this matters: any host implementing chain expansion MUST verify
+ * the source pack's signature before resolving + expanding (step 2 of
+ * the expansion algorithm). If chain packs needed a different signing
+ * recipe than node packs, implementers would need two verification
+ * paths — that's a footgun. The spec explicitly designs them to share.
+ *
+ * @see spec/v1/workflow-chain-packs.md §"Expansion semantics" step 2
+ * @see spec/v1/node-packs.md §Signing
+ * @see RFCS/0013-workflow-chain-packs.md
+ */
+
+import { describe, it, expect } from 'vitest';
+import { generateKeyPairSync, sign, verify } from 'node:crypto';
+
+/** Canonical workflow-chain pack manifest used as the signing target.
+ *  Mirrors the spec doc's Positive example, kept tight so the test
+ *  focuses on the signing path, not the manifest shape. */
+const MANIFEST = {
+  name: 'vendor.acme.editor-presets',
+  version: '1.0.0',
+  kind: 'workflow-chain',
+  description: 'Sample workflow-chain pack used by signature-verification conformance.',
+  engines: { openwop: '>=1.0.0 <2.0.0' },
+  chains: [
+    {
+      chainId: 'vendor.acme.generatePRD',
+      version: '1.0.0',
+      label: 'Generate PRD',
+      description: 'Single-node AI call.',
+      parameters: { type: 'object', properties: { productIdea: { type: 'string' } } },
+      dag: {
+        nodes: [{ id: 'prd-call', typeId: 'core.ai.callPrompt', config: {} }],
+        edges: [],
+      },
+    },
+  ],
+};
+
+/** Canonical byte serialization of the manifest used for signing.
+ *  Matches the recipe in node-packs.md §Signing: "Ed25519 signature
+ *  over `pack.json`" — the on-disk JSON bytes ARE the signing payload.
+ *  Production tooling would use the EXACT bytes from `pack.json` in the
+ *  tarball (preserved whitespace, byte-for-byte) so the verification
+ *  recipe is deterministic. */
+function manifestBytes(): Buffer {
+  return Buffer.from(JSON.stringify(MANIFEST, null, 2));
+}
+
+describe('category: workflow-chain pack signature — Ed25519 verification reuse from node-packs', () => {
+  it('valid manifest + valid signature MUST verify (positive path)', () => {
+    const { privateKey, publicKey } = generateKeyPairSync('ed25519');
+    const manifest = manifestBytes();
+    // Per node-packs.md §Signing: Ed25519, no separate hash step (Ed25519
+    // signs the message directly). The `algorithm` arg to crypto.sign is
+    // `null` for Ed25519 — confirmed by Node's docs.
+    const signature = sign(null, manifest, privateKey);
+    const ok = verify(null, manifest, publicKey, signature);
+    expect(
+      ok,
+      'Per workflow-chain-packs.md §"Expansion semantics" step 2: the signature recipe is IDENTICAL to node-packs (Ed25519 over pack.json bytes). A valid pair MUST verify with the canonical recipe.',
+    ).toBe(true);
+  });
+
+  it('tampered manifest MUST fail verification (sha-level tamper detection)', () => {
+    const { privateKey, publicKey } = generateKeyPairSync('ed25519');
+    const original = manifestBytes();
+    const signature = sign(null, original, privateKey);
+    // Tamper: change a single byte in the manifest after signing. This
+    // simulates a registry-side or man-in-the-middle modification — the
+    // signing recipe MUST detect ANY byte-level change.
+    const tampered = Buffer.from(original);
+    tampered[10] = tampered[10]! ^ 0x01;
+    const ok = verify(null, tampered, publicKey, signature);
+    expect(
+      ok,
+      'Per node-packs.md §Signing (reused unchanged for chain packs): Ed25519 verification MUST detect any byte-level tamper to the signed payload.',
+    ).toBe(false);
+  });
+
+  it('wrong-key signature MUST fail verification', () => {
+    const { privateKey: legitPrivKey } = generateKeyPairSync('ed25519');
+    const { publicKey: attackerPubKey } = generateKeyPairSync('ed25519');
+    const manifest = manifestBytes();
+    const signature = sign(null, manifest, legitPrivKey);
+    // Try to verify with a DIFFERENT public key than the one paired with
+    // the signing private key. This is the supply-chain attack the
+    // signing recipe defends against (attacker substitutes their own
+    // key in the manifest's `signing.publicKeyRef`).
+    const ok = verify(null, manifest, attackerPubKey, signature);
+    expect(
+      ok,
+      'Ed25519 verification MUST fail when the public key doesn\'t match the private key that produced the signature — the spec\'s trust model depends on this property.',
+    ).toBe(false);
+  });
+
+  it('chain pack manifests carry the SAME signing block shape as node packs', () => {
+    // node-packs.md §signing declares `pack.json` MAY carry a `signing`
+    // block with `publicKeyRef` / `signatureRef` / `method`. Chain packs
+    // reuse the same shape unchanged — workflow-chain-pack-manifest.
+    // schema.json's `$defs.Signing` is byte-identical to the node-pack
+    // schema's `$defs.Signing`. This assertion documents the spec
+    // design intent so future schema evolution doesn't silently
+    // diverge.
+    const signedManifest = {
+      ...MANIFEST,
+      signing: {
+        publicKeyRef: 'keys/2026-05.pem',
+        signatureRef: 'pack.json.sig',
+        method: 'manual' as const,
+      },
+    };
+    expect(
+      signedManifest.signing.method,
+      'workflow-chain packs MUST accept the same signing block keys as node packs (publicKeyRef + signatureRef + method) per spec design.',
+    ).toBe('manual');
+    expect(signedManifest.signing.publicKeyRef).toBe('keys/2026-05.pem');
+    expect(signedManifest.signing.signatureRef).toBe('pack.json.sig');
+  });
+});

package/src/scenarios/workflow-chain-unresolvable-typeid.test.ts

@@ -0,0 +1,170 @@
+/**
+ * Workflow-chain expansion — unresolvable typeId rejection per
+ * `workflow-chain-packs.md` §"Expansion semantics (normative)" step 3
+ * + `workflow-chain-packs.md` §"Error codes" `chain_unresolvable_typeid`.
+ *
+ * Server-free scenario. Asserts that when a chain's `dag.nodes[].typeId`
+ * references an UNPUBLISHED typeId (one the destination host's pack
+ * registry can't resolve), expansion is rejected with
+ * `chain_unresolvable_typeid` BEFORE any node ids are rewritten or
+ * placeholders substituted.
+ *
+ * The "rejection at expansion time" path is load-bearing for the
+ * "additive — no new dispatch surface" invariant: if expansion produced
+ * a workflow referencing an unknown typeId, the dispatching engine
+ * would fail at run time with `unknown_typeid` and the user would see
+ * a confusing failure far from the chain-pack tile they dragged.
+ * Rejecting at edit time keeps the failure local to the author's
+ * action.
+ *
+ * Per the spec's "Negative: chain references unpublished typeId"
+ * example: the pack's manifest validation does NOT cross-check
+ * published typeId existence (cycle issues + registry-availability
+ * concerns); only the host-editor-time expansion step verifies — by
+ * which point the destination host's pack registry has authoritative
+ * knowledge of which typeIds it can resolve.
+ *
+ * @see spec/v1/workflow-chain-packs.md §"Expansion semantics" step 3
+ * @see spec/v1/workflow-chain-packs.md §"Error codes"
+ * @see conformance/src/lib/workflow-chain-expansion.ts
+ * @see RFCS/0013-workflow-chain-packs.md
+ */
+
+import { describe, it, expect } from 'vitest';
+import {
+  expandChain,
+  ChainUnresolvableTypeIdError,
+  type WorkflowChain,
+} from '../lib/workflow-chain-expansion.js';
+
+const CHAIN_WITH_UNKNOWN_TYPEID: WorkflowChain = {
+  chainId: 'vendor.acme.someChain',
+  version: '1.0.0',
+  label: 'Some Chain',
+  description: 'References an unpublished typeId — should fail expansion.',
+  parameters: {},
+  dag: {
+    nodes: [
+      { id: 'n1', typeId: 'made.up.foo', config: {} },
+    ],
+    edges: [],
+  },
+};
+
+/** Resolver that only accepts a hardcoded set of "known" typeIds — the
+ *  set the destination host's pack registry can satisfy. Mimics the
+ *  realistic host-editor-time check. */
+const KNOWN_TYPEIDS = new Set(['core.identity', 'core.ai.callPrompt']);
+const isKnown = (typeId: string): boolean => KNOWN_TYPEIDS.has(typeId);
+
+describe('category: workflow-chain expansion — unresolvable typeId rejection', () => {
+  it('throws ChainUnresolvableTypeIdError when chain references an unknown typeId', () => {
+    expect(
+      () =>
+        expandChain(CHAIN_WITH_UNKNOWN_TYPEID, {
+          expansionId: 'x',
+          params: {},
+          isTypeIdResolvable: isKnown,
+        }),
+      'Per spec §"Expansion semantics" step 3: hosts MUST reject expansion with `chain_unresolvable_typeid` when any fragment node\'s typeId can\'t be resolved by the destination host.',
+    ).toThrow(ChainUnresolvableTypeIdError);
+  });
+
+  it('error carries the offending typeId AND the chainId in `details`', () => {
+    try {
+      expandChain(CHAIN_WITH_UNKNOWN_TYPEID, {
+        expansionId: 'x',
+        params: {},
+        isTypeIdResolvable: isKnown,
+      });
+      expect.fail('expandChain MUST have thrown ChainUnresolvableTypeIdError');
+    } catch (err) {
+      expect(err, 'expected ChainUnresolvableTypeIdError').toBeInstanceOf(
+        ChainUnresolvableTypeIdError,
+      );
+      const e = err as ChainUnresolvableTypeIdError;
+      expect(
+        e.code,
+        'Per spec §"Error codes": the wire-level error code MUST be `chain_unresolvable_typeid`.',
+      ).toBe('chain_unresolvable_typeid');
+      expect(
+        e.typeId,
+        'The error MUST surface the offending typeId so the host editor can render an actionable diagnostic.',
+      ).toBe('made.up.foo');
+      expect(
+        e.chainId,
+        'The error MUST surface the chainId so the host editor knows which chain-pack tile triggered the rejection.',
+      ).toBe('vendor.acme.someChain');
+    }
+  });
+
+  it('rejection happens BEFORE any id rewriting or placeholder substitution', () => {
+    // If the spec allowed expansion to proceed and produce a half-built
+    // fragment with an unknown typeId, downstream tooling would see a
+    // workflow with an undispatchable node. The contract is "reject
+    // cleanly at the resolution step, no partial output."
+    let threw = false;
+    try {
+      expandChain(CHAIN_WITH_UNKNOWN_TYPEID, {
+        expansionId: 'x',
+        params: { foo: 'bar' },
+        isTypeIdResolvable: isKnown,
+      });
+    } catch {
+      threw = true;
+    }
+    expect(
+      threw,
+      'Expansion MUST throw before producing any output — host editors rely on the "no partial expansion" guarantee to keep parent workflows clean on rejection.',
+    ).toBe(true);
+  });
+
+  it('accepts the chain when every typeId IS resolvable', () => {
+    const resolvable: WorkflowChain = {
+      ...CHAIN_WITH_UNKNOWN_TYPEID,
+      dag: {
+        nodes: [{ id: 'n1', typeId: 'core.identity', config: {} }],
+        edges: [],
+      },
+    };
+    expect(
+      () =>
+        expandChain(resolvable, {
+          expansionId: 'x',
+          params: {},
+          isTypeIdResolvable: isKnown,
+        }),
+      'Sanity: when every typeId resolves, expansion MUST proceed without throwing.',
+    ).not.toThrow();
+  });
+
+  it('throws on the FIRST unknown typeId encountered (fail-fast)', () => {
+    // Chain with two nodes — one resolvable, one not. The unresolvable one
+    // is second. The throw MUST identify the second one (the actual
+    // offender), not silently skip it.
+    const mixed: WorkflowChain = {
+      ...CHAIN_WITH_UNKNOWN_TYPEID,
+      dag: {
+        nodes: [
+          { id: 'n1', typeId: 'core.identity', config: {} },
+          { id: 'n2', typeId: 'made.up.foo', config: {} },
+        ],
+        edges: [],
+      },
+    };
+    try {
+      expandChain(mixed, {
+        expansionId: 'x',
+        params: {},
+        isTypeIdResolvable: isKnown,
+      });
+      expect.fail('MUST have thrown on n2\'s unknown typeId');
+    } catch (err) {
+      const e = err as ChainUnresolvableTypeIdError;
+      expect(
+        e.typeId,
+        'When multiple nodes have unknown typeIds, the throw MUST identify the first unknown one encountered in declaration order.',
+      ).toBe('made.up.foo');
+    }
+  });
+});