@openwop/openwop-conformance 1.1.1 → 1.3.0

package/src/scenarios/workflow-chain-pack-manifest-validation.test.ts

@@ -0,0 +1,232 @@
+/**
+ * Workflow-chain pack manifest validation — `workflow-chain-packs.md` §Manifest format
+ * + `schemas/workflow-chain-pack-manifest.schema.json` (closes RFC 0013 Phase 1).
+ *
+ * Server-free schema-validation scenario. Exercises the new
+ * `workflow-chain-pack-manifest.schema.json` with a positive sample and
+ * two negative samples derived from the RFC's Negative examples:
+ *
+ *   1. Positive: a valid `kind: "workflow-chain"` manifest with a single
+ *      `chains[]` entry validates cleanly.
+ *   2. Negative — kind/contents mismatch: a manifest carrying BOTH
+ *      `chains[]` AND `nodes[]` is rejected. Surface-level outcome at
+ *      the registry HTTP API is `pack_kind_invalid` per the spec;
+ *      schema-level outcome is an `additionalProperties` violation on
+ *      `nodes` (the workflow-chain schema does not declare that field).
+ *   3. Negative — invalid `chainId`: a chain entry whose `chainId` does
+ *      not match the reverse-DNS pattern is rejected with a `pattern`
+ *      violation.
+ *
+ * Capability-gated scenarios for end-to-end expansion
+ * (`workflow-chain-expansion.test.ts`) and signature verification
+ * (`workflow-chain-pack-signature-verification.test.ts`) are deferred
+ * to Phase 2/3 per the RFC.
+ *
+ * @see spec/v1/workflow-chain-packs.md
+ * @see schemas/workflow-chain-pack-manifest.schema.json
+ * @see RFCS/0013-workflow-chain-packs.md
+ */
+
+import { describe, it, expect } from 'vitest';
+import { readFileSync, existsSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import Ajv2020 from 'ajv/dist/2020.js';
+import addFormats from 'ajv-formats';
+import type { ErrorObject } from 'ajv';
+import { SCHEMAS_DIR, V1_DIR } from '../lib/paths.js';
+
+const SCHEMA_PATH = join(SCHEMAS_DIR, 'workflow-chain-pack-manifest.schema.json');
+// In-repo example pack — proves the schema validates a non-trivial
+// real-world-shaped manifest (closes RFC 0013 Phase 4 in-tree path).
+// Resolved relative to the repo root (V1_DIR is non-null in the repo
+// layout AND in any in-tree mirror; null under the published-tarball
+// layout where examples/ isn't bundled). Skipped cleanly when unavailable.
+const REPO_ROOT = V1_DIR ? dirname(dirname(V1_DIR)) : null;
+const EXAMPLE_PACK_PATH = REPO_ROOT
+  ? join(REPO_ROOT, 'examples/packs/workflow-chain-sample/pack.json')
+  : null;
+
+describe('category: workflow-chain-pack manifest validation', () => {
+  const ajv = new Ajv2020({ allErrors: true, strict: false });
+  addFormats(ajv);
+  const schema = JSON.parse(readFileSync(SCHEMA_PATH, 'utf8'));
+  const validate = ajv.compile(schema);
+
+  it('positive: a valid workflow-chain pack manifest validates cleanly', () => {
+    const manifest = {
+      name: 'vendor.acme.editor-presets',
+      version: '1.0.0',
+      kind: 'workflow-chain',
+      description: 'Author-time editor presets.',
+      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 with PRD authoring prompt.',
+          parameters: {
+            type: 'object',
+            required: ['productIdea'],
+            properties: {
+              productIdea: { type: 'string' },
+              targetAudience: { type: 'string', default: '' },
+            },
+          },
+          dag: {
+            nodes: [
+              {
+                id: 'prd-call',
+                typeId: 'core.ai.callPrompt',
+                config: {
+                  systemPrompt: 'Write a PRD for: {{params.productIdea}}',
+                  envelopeType: 'prd.create',
+                  provider: 'anthropic',
+                },
+              },
+            ],
+            edges: [],
+          },
+          outputs: {
+            prdId: { type: 'string', description: 'Created PRD artifact id.' },
+          },
+          capabilities: ['side-effectful'],
+        },
+      ],
+    };
+    const ok = validate(manifest);
+    const errs = (validate.errors ?? [])
+      .map((e: ErrorObject) => `${e.instancePath || '/'}: ${e.message}`)
+      .join('\n');
+    expect(
+      ok,
+      `Positive sample MUST validate against workflow-chain-pack-manifest.schema.json — got:\n${errs}`,
+    ).toBe(true);
+  });
+
+  it('negative: manifest mixing chains[] AND nodes[] is rejected (pack_kind_invalid)', () => {
+    // Per workflow-chain-packs.md §Pack kind discriminator: "Manifests MUST
+    // have exactly one of nodes[] (kind=node) OR chains[] (kind=workflow-chain).
+    // Manifests containing both MUST be rejected at manifest validation with
+    // error code pack_kind_invalid." The schema-level enforcement is via
+    // additionalProperties: false (the workflow-chain schema does not declare
+    // a `nodes` property, so its presence triggers the violation).
+    const manifest = {
+      name: 'vendor.acme.mixed',
+      version: '1.0.0',
+      kind: 'workflow-chain',
+      engines: { openwop: '>=1.0.0' },
+      nodes: [
+        { typeId: 'vendor.acme.foo', version: '1.0.0', category: 'data', role: 'pure' },
+      ],
+      chains: [
+        {
+          chainId: 'vendor.acme.bar',
+          version: '1.0.0',
+          label: 'Bar',
+          description: 'x',
+          parameters: {},
+          dag: { nodes: [{ id: 'n', typeId: 'core.identity' }], edges: [] },
+        },
+      ],
+    };
+    const ok = validate(manifest);
+    expect(
+      ok,
+      'Manifest with both nodes[] and chains[] MUST fail workflow-chain schema validation (pack_kind_invalid at the registry surface).',
+    ).toBe(false);
+    const hasAdditionalPropertiesErr = (validate.errors ?? []).some(
+      (e: ErrorObject) => e.keyword === 'additionalProperties',
+    );
+    expect(
+      hasAdditionalPropertiesErr,
+      'Expected an `additionalProperties` violation flagging the unexpected `nodes` field.',
+    ).toBe(true);
+  });
+
+  it('negative: chain entry with invalid chainId is rejected (pattern violation)', () => {
+    // Per workflow-chain-packs.md §Chain entry shape: chainId MUST match the
+    // reverse-DNS pattern `^[a-z][a-zA-Z0-9._-]*$`. An empty string, leading
+    // digit, or any other shape violating the pattern fails validation.
+    const manifest = {
+      name: 'vendor.acme.editor-presets',
+      version: '1.0.0',
+      kind: 'workflow-chain',
+      engines: { openwop: '>=1.0.0' },
+      chains: [
+        {
+          // INVALID — leading digit, contains uppercase that breaks the
+          // first-char rule, AND a slash that no chainId is allowed to carry.
+          chainId: '9Bad/Id',
+          version: '1.0.0',
+          label: 'Bad',
+          description: 'x',
+          parameters: {},
+          dag: { nodes: [{ id: 'n', typeId: 'core.identity' }], edges: [] },
+        },
+      ],
+    };
+    const ok = validate(manifest);
+    expect(
+      ok,
+      'Manifest with invalid chainId MUST fail workflow-chain schema validation.',
+    ).toBe(false);
+    const hasPatternErr = (validate.errors ?? []).some(
+      (e: ErrorObject) =>
+        e.keyword === 'pattern' && (e.instancePath ?? '').includes('chainId'),
+    );
+    expect(
+      hasPatternErr,
+      'Expected a `pattern` violation on the chains[].chainId field.',
+    ).toBe(true);
+  });
+
+  it('positive: the in-repo example pack at examples/packs/workflow-chain-sample/ validates against the schema', () => {
+    if (!EXAMPLE_PACK_PATH || !existsSync(EXAMPLE_PACK_PATH)) {
+      // Published-tarball layout doesn't ship examples/; skip cleanly.
+      return;
+    }
+    const manifest = JSON.parse(readFileSync(EXAMPLE_PACK_PATH, 'utf8'));
+    const ok = validate(manifest);
+    const errs = (validate.errors ?? [])
+      .map((e: ErrorObject) => `${e.instancePath || '/'}: ${e.message}`)
+      .join('\n');
+    expect(
+      ok,
+      `examples/packs/workflow-chain-sample/pack.json MUST validate against workflow-chain-pack-manifest.schema.json (closes RFC 0013 Phase 4 in-tree path). Errors:\n${errs}`,
+    ).toBe(true);
+    // Spot-check the structural claims the example README makes:
+    expect(manifest.kind, 'example pack MUST declare kind: "workflow-chain"').toBe(
+      'workflow-chain',
+    );
+    expect(
+      Array.isArray(manifest.chains) && manifest.chains.length === 2,
+      'example pack MUST ship exactly 2 chains (1-node + 2-node shapes) per its README contract',
+    ).toBe(true);
+  });
+
+  it('negative: omitting kind field rejects (kind is required)', () => {
+    // Defensive — the workflow-chain schema makes `kind` REQUIRED so a
+    // node-pack-shape manifest can't accidentally validate against it.
+    const manifest = {
+      name: 'vendor.acme.editor-presets',
+      version: '1.0.0',
+      engines: { openwop: '>=1.0.0' },
+      chains: [
+        {
+          chainId: 'vendor.acme.x',
+          version: '1.0.0',
+          label: 'X',
+          description: 'x',
+          parameters: {},
+          dag: { nodes: [{ id: 'n', typeId: 'core.identity' }], edges: [] },
+        },
+      ],
+    };
+    const ok = validate(manifest);
+    expect(
+      ok,
+      'Manifest without kind: "workflow-chain" MUST fail this schema (the other path is node-pack-manifest.schema.json).',
+    ).toBe(false);
+  });
+});

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');
+    }
+  });
+});