@openwop/openwop-conformance 1.1.0 → 1.2.0

package/src/lib/behavior-gate.ts

@@ -18,6 +18,18 @@
  *     scenario exercises real behavior — useful for hosts that want to
  *     claim full coverage in `INTEROP-MATRIX.md`.
  *
+ *   - **Strict-mode opt-out (skip in strict mode too):** set
+ *     `OPENWOP_OPTED_OUT_PROFILES=name1,name2,...` to declare that the
+ *     host operator has deliberately chosen NOT to implement those
+ *     profiles. In strict mode the gate skips them with a "honest
+ *     opt-out" log line instead of failing — minimal hosts that
+ *     advertise only what they implement can still go strict-mode
+ *     green without falsifying capability claims. Conflict check:
+ *     if a profile appears in BOTH `OPENWOP_OPTED_OUT_PROFILES` AND
+ *     the host's discovery `capabilities.auth.profiles[]` (or
+ *     equivalent), the gate logs a loud warning — opt-outs and
+ *     advertisements are mutually exclusive.
+ *
  * Usage:
  *
  *   ```ts
@@ -42,18 +54,45 @@ import { loadEnv } from './env.js';
 
 /**
  * Returns true if the scenario should proceed with assertions (advertised),
- * false if the scenario should `return` early (default-mode skip). In strict
- * mode (`OPENWOP_REQUIRE_BEHAVIOR=true`), throws if not advertised — so the
- * caller never actually receives `false` in that mode.
+ * false if the scenario should `return` early (default-mode skip OR
+ * strict-mode honest opt-out). In strict mode (`OPENWOP_REQUIRE_BEHAVIOR=true`)
+ * with `profileName` NOT in `OPENWOP_OPTED_OUT_PROFILES`, throws — so the
+ * caller never receives `false` in that combination.
+ *
+ * If the host BOTH advertises the profile AND the operator listed it in
+ * the opt-out env var, surface a warning (likely typo) and treat as
+ * advertised (proceed). Advertisement always wins over opt-out: opting
+ * out of a profile you actually implement is meaningless.
  */
 export function behaviorGate(profileName: string, advertised: boolean): boolean {
+  const env = loadEnv();
+  const optedOut = env.optedOutProfiles.has(profileName);
+
+  if (advertised && optedOut) {
+    // eslint-disable-next-line no-console
+    console.warn(
+      `[${profileName}] both ADVERTISED by the host AND listed in OPENWOP_OPTED_OUT_PROFILES — ` +
+        `opt-out is ignored. Remove from the env var to clear this warning.`,
+    );
+  }
+
   if (advertised) return true;
 
-  const env = loadEnv();
+  if (optedOut) {
+    // Honest opt-out: the operator declared the host does not implement
+    // this profile. Skip in BOTH default and strict mode.
+    // eslint-disable-next-line no-console
+    console.warn(
+      `[${profileName}] honest opt-out (OPENWOP_OPTED_OUT_PROFILES); skipping`,
+    );
+    return false;
+  }
+
   if (env.requireBehavior) {
     expect(
       advertised,
-      `OPENWOP_REQUIRE_BEHAVIOR=true: host MUST advertise the ${profileName} profile for this scenario to run. ` +
+      `OPENWOP_REQUIRE_BEHAVIOR=true: host MUST advertise the ${profileName} profile for this scenario to run, ` +
+        `or declare opt-out via OPENWOP_OPTED_OUT_PROFILES=${profileName}. ` +
         `See conformance/coverage.md §"Capability-gated scenarios".`,
     ).toBe(true);
     // expect.toBe(true) throws; we won't reach here.

package/src/lib/env.ts

@@ -16,6 +16,15 @@
  *     Default is false — scenarios skip with a warning so default conformance
  *     runs cover what the host has implemented. See `lib/behavior-gate.ts`
  *     and `conformance/coverage.md` §"Capability-gated scenarios".
+ *
+ *   OPENWOP_OPTED_OUT_PROFILES — comma-separated profile names the host
+ *     operator has DELIBERATELY chosen not to implement. In strict mode
+ *     these scenarios skip (logged as "honest opt-out") rather than
+ *     failing — distinguishes "host doesn't claim this surface" (good)
+ *     from "host claims but doesn't deliver" (bug). Lets honest minimal
+ *     hosts go strict-mode green without falsifying capability claims.
+ *     Example for SQLite:
+ *       OPENWOP_OPTED_OUT_PROFILES=openwop-production,openwop-auth-mtls
  */
 
 export interface ConformanceEnv {
@@ -24,6 +33,15 @@ export interface ConformanceEnv {
   readonly implementationName: string;
   readonly implementationVersion: string;
   readonly requireBehavior: boolean;
+  /**
+   * Profiles the host operator has declared the host does NOT claim. Set
+   * via `OPENWOP_OPTED_OUT_PROFILES=name1,name2`. In strict mode, the
+   * behavior-gate honors this set as PASS-by-opt-out rather than failing
+   * the scenario. Never include a profile the host actually advertises —
+   * that's a typo, not an opt-out, and `behaviorGate` will surface a
+   * warning if it detects the conflict.
+   */
+  readonly optedOutProfiles: ReadonlySet<string>;
 }
 
 let cached: ConformanceEnv | null = null;
@@ -48,12 +66,21 @@ export function loadEnv(): ConformanceEnv {
   // Strip trailing slash so URL composition is consistent.
   const normalizedBase = baseUrl.replace(/\/$/, '');
 
+  const optedOutRaw = process.env.OPENWOP_OPTED_OUT_PROFILES?.trim() ?? '';
+  const optedOutProfiles = new Set(
+    optedOutRaw
+      .split(',')
+      .map((s) => s.trim())
+      .filter((s) => s.length > 0),
+  );
+
   cached = {
     baseUrl: normalizedBase,
     apiKey,
     implementationName: process.env.OPENWOP_IMPLEMENTATION_NAME?.trim() ?? 'unknown',
     implementationVersion: process.env.OPENWOP_IMPLEMENTATION_VERSION?.trim() ?? 'unknown',
     requireBehavior: process.env.OPENWOP_REQUIRE_BEHAVIOR === 'true',
+    optedOutProfiles,
   };
   return cached;
 }

package/src/lib/webhook-receiver.ts

@@ -0,0 +1,137 @@
+/**
+ * Reference webhook receiver for the conformance suite — implements
+ * the verification contract per `spec/v1/webhooks.md` §"Signature
+ * recipe" + §"Replay-attack resistance" so adversarial-input scenarios
+ * can verify that a properly-implemented receiver rejects the
+ * documented failure modes.
+ *
+ * Mirrors the SDK's verifyWebhookSignature helper (sdk/typescript/src/
+ * webhook-helpers.ts) but inlined here so the conformance suite stays
+ * dependency-free vs. the SDK. The two MUST produce identical
+ * outcomes for the same inputs.
+ *
+ * @see spec/v1/webhooks.md §"Signature recipe"
+ * @see sdk/typescript/src/webhook-helpers.ts (canonical SDK
+ *      implementation; this file is a conformance-suite mirror)
+ */
+
+import { createHmac, timingSafeEqual } from 'node:crypto';
+
+export const DEFAULT_FRESHNESS_WINDOW_SECONDS = 300;
+
+export type WebhookRejectionReason =
+  | 'signature_mismatch'
+  | 'timestamp_expired'
+  | 'timestamp_too_far_in_future'
+  | 'malformed_signature_header'
+  | 'malformed_timestamp_header'
+  | 'wrong_algorithm'
+  | 'duplicate_signature';
+
+export type WebhookVerifyResult =
+  | { accepted: true }
+  | { accepted: false; reason: WebhookRejectionReason };
+
+export interface WebhookReceiverState {
+  /** Set of signature values the receiver has already accepted (anti-replay). */
+  acceptedSignatures: Set<string>;
+}
+
+export function createReceiverState(): WebhookReceiverState {
+  return { acceptedSignatures: new Set() };
+}
+
+export interface VerifyOptions {
+  /** Default 5 minutes per spec. Set 0 to disable freshness check. */
+  freshnessWindowSeconds?: number;
+  /** Override `now` (unix seconds) for deterministic tests. */
+  nowSeconds?: number;
+}
+
+/**
+ * Verify a single webhook delivery against the canonical recipe.
+ * Returns `{ accepted: true }` on success; `{ accepted: false, reason }`
+ * otherwise. Updates `state.acceptedSignatures` on acceptance for
+ * replay-attack detection on subsequent calls.
+ *
+ * Receivers MUST pass the **exact** request body bytes — parsed-and-
+ * reserialized JSON will fail verification.
+ */
+export function verifyWebhookDelivery(
+  secret: string,
+  signatureHeader: string,
+  algorithmHeader: string | undefined,
+  timestampHeader: string,
+  rawBody: string | Buffer,
+  state: WebhookReceiverState,
+  options: VerifyOptions = {},
+): WebhookVerifyResult {
+  // 1. Algorithm gating. Hosts MAY include an explicit
+  //    X-openwop-Signature-Algorithm header; receivers MUST refuse
+  //    anything other than `v1` per webhooks.md §"Signature algorithm
+  //    versioning". Absence is treated as the v1 default.
+  if (algorithmHeader !== undefined && algorithmHeader !== 'v1') {
+    return { accepted: false, reason: 'wrong_algorithm' };
+  }
+
+  // 2. Signature header parse.
+  if (!signatureHeader.startsWith('v1=')) {
+    return { accepted: false, reason: 'malformed_signature_header' };
+  }
+  const providedHex = signatureHeader.slice(3);
+  if (!/^[0-9a-f]+$/i.test(providedHex)) {
+    return { accepted: false, reason: 'malformed_signature_header' };
+  }
+
+  // 3. Anti-replay: receivers MUST refuse a signature value seen
+  //    before, even if the timestamp would otherwise be fresh
+  //    (defense-in-depth against an attacker resending a captured
+  //    delivery before the original's timestamp window expires).
+  if (state.acceptedSignatures.has(signatureHeader)) {
+    return { accepted: false, reason: 'duplicate_signature' };
+  }
+
+  // 4. Timestamp parse + freshness window.
+  const timestamp = Number(timestampHeader);
+  if (!Number.isInteger(timestamp) || timestamp <= 0) {
+    return { accepted: false, reason: 'malformed_timestamp_header' };
+  }
+  const window = options.freshnessWindowSeconds ?? DEFAULT_FRESHNESS_WINDOW_SECONDS;
+  if (window > 0) {
+    const now = options.nowSeconds ?? Math.floor(Date.now() / 1000);
+    const delta = now - timestamp;
+    if (delta > window) return { accepted: false, reason: 'timestamp_expired' };
+    if (delta < -window) return { accepted: false, reason: 'timestamp_too_far_in_future' };
+  }
+
+  // 5. HMAC recompute + constant-time compare.
+  const bodyStr = typeof rawBody === 'string' ? rawBody : rawBody.toString('utf8');
+  const expectedHex = createHmac('sha256', secret).update(`${timestamp}.${bodyStr}`, 'utf8').digest('hex');
+  const providedBuf = Buffer.from(providedHex, 'hex');
+  const expectedBuf = Buffer.from(expectedHex, 'hex');
+  if (providedBuf.length !== expectedBuf.length || !timingSafeEqual(providedBuf, expectedBuf)) {
+    return { accepted: false, reason: 'signature_mismatch' };
+  }
+
+  // 6. Accept + record for replay detection.
+  state.acceptedSignatures.add(signatureHeader);
+  return { accepted: true };
+}
+
+/**
+ * Sign a payload the way the host would — useful for building
+ * adversarial-input fixtures in scenarios.
+ */
+export function signPayload(
+  secret: string,
+  timestamp: number,
+  rawBody: string | Buffer,
+): { signatureHeader: string; timestampHeader: string; algorithmHeader: 'v1' } {
+  const bodyStr = typeof rawBody === 'string' ? rawBody : rawBody.toString('utf8');
+  const hex = createHmac('sha256', secret).update(`${timestamp}.${bodyStr}`, 'utf8').digest('hex');
+  return {
+    signatureHeader: `v1=${hex}`,
+    timestampHeader: String(timestamp),
+    algorithmHeader: 'v1',
+  };
+}

package/src/lib/workflow-chain-expansion.ts

@@ -0,0 +1,213 @@
+/**
+ * Workflow-chain pack expansion — reference implementation of the
+ * 9-step host-editor expansion semantics from
+ * `spec/v1/workflow-chain-packs.md` §"Expansion semantics (normative)".
+ *
+ * Pure function. Zero I/O, zero crypto. Hosts implementing chain
+ * expansion in their workflow editors MAY import this directly OR
+ * adapt the algorithm into their language of choice — the contract
+ * this code encodes is the spec, not the code itself.
+ *
+ * What this implements:
+ *   - Step 3: validate referenced typeIds resolve (delegated to caller via
+ *     `isTypeIdResolvable` predicate)
+ *   - Step 5: `{{params.<name>}}` literal substitution (recursive into
+ *     nested string fields inside `config` / `inputs`)
+ *   - Step 6: per-expansion node-id rewrite with a chainId-derived prefix
+ *     for collision-free splice into the parent workflow
+ *   - Step 8: capability propagation (chain.capabilities[] → every
+ *     expanded WorkflowNode.capabilities[])
+ *   - Edge endpoint rewriting (`from`/`to` ids that reference fragment
+ *     nodes get the same prefix)
+ *
+ * What this deliberately DOESN'T implement (host-specific concerns):
+ *   - Step 1: registry resolution (network/storage path is host-specific)
+ *   - Step 2: signature verification (use `node:crypto`'s Ed25519 path —
+ *     see workflow-chain-pack-signature-verification.test.ts)
+ *   - Step 4: parameter-form prompting (host-UI concern)
+ *   - Step 7: splice into parent workflow (host-editor concern; this
+ *     function returns the rewritten fragment ready to be appended)
+ *   - Step 9: persistence (host-storage concern)
+ *
+ * @see spec/v1/workflow-chain-packs.md §"Expansion semantics (normative)"
+ * @see RFCS/0013-workflow-chain-packs.md
+ */
+
+/** A workflow-chain entry as it appears in a pack manifest. */
+export interface WorkflowChain {
+  chainId: string;
+  version: string;
+  label: string;
+  description: string;
+  parameters: object;
+  dag: { nodes: ReadonlyArray<FragmentNode>; edges?: ReadonlyArray<FragmentEdge> };
+  outputs?: Record<string, { type: string; description: string }>;
+  capabilities?: ReadonlyArray<'streamable' | 'cacheable' | 'side-effectful' | 'mcp-exportable'>;
+}
+
+export interface FragmentNode {
+  id: string;
+  typeId: string;
+  name?: string;
+  position?: { x: number; y: number };
+  config?: Record<string, unknown>;
+  inputs?: Record<string, unknown>;
+}
+
+export interface FragmentEdge {
+  from: string;
+  to: string;
+  condition?: string;
+}
+
+/** Per-expansion context the caller supplies. */
+export interface ExpansionContext {
+  /** Caller-supplied unique tag for this expansion (e.g., 4-hex random).
+   *  Combined with the chainId slug to namespace expanded node ids so
+   *  the same chain can be expanded multiple times within one parent
+   *  workflow without id collisions. */
+  expansionId: string;
+  /** Author-supplied parameter values, ALREADY VALIDATED against the
+   *  chain's `parameters` JSON Schema. This function does NOT re-validate
+   *  — the caller MUST ajv-compile `chain.parameters` and reject invalid
+   *  input with `chain_parameter_invalid` BEFORE calling. */
+  params: Record<string, unknown>;
+  /** Predicate the caller supplies for typeId resolution (step 3). Should
+   *  return `true` if the typeId is registered with the destination host
+   *  (either reserved `core.*` or published via a known node pack). */
+  isTypeIdResolvable: (typeId: string) => boolean;
+}
+
+/** Result of expansion — ready to be spliced into a parent workflow's
+ *  `nodes[]` / `edges[]`. */
+export interface ExpandedFragment {
+  nodes: ReadonlyArray<{
+    id: string;
+    typeId: string;
+    name?: string;
+    position?: { x: number; y: number };
+    config?: Record<string, unknown>;
+    inputs?: Record<string, unknown>;
+    capabilities?: ReadonlyArray<string>;
+  }>;
+  edges: ReadonlyArray<{ from: string; to: string; condition?: string }>;
+  /** Map of original-fragment-id → rewritten-id, so the caller can
+   *  wire the parent workflow's adjacent edges into the expansion. */
+  idMap: ReadonlyMap<string, string>;
+}
+
+/** Thrown when expansion encounters a chain that references a typeId the
+ *  destination host can't resolve. Carries both the offending `typeId`
+ *  and the `chainId` for diagnostic reporting. The error message uses
+ *  the wire-level error code `chain_unresolvable_typeid` per
+ *  `workflow-chain-packs.md` §"Error codes". */
+export class ChainUnresolvableTypeIdError extends Error {
+  readonly code = 'chain_unresolvable_typeid';
+  constructor(readonly typeId: string, readonly chainId: string) {
+    super(`chain_unresolvable_typeid: '${typeId}' in chain '${chainId}'`);
+    this.name = 'ChainUnresolvableTypeIdError';
+  }
+}
+
+const PARAM_PATTERN = /\{\{params\.([a-zA-Z_][a-zA-Z0-9_]*)\}\}/g;
+
+/** Recursive literal substitution of `{{params.<name>}}` placeholders in
+ *  any string field. Non-string values pass through unchanged; nested
+ *  arrays/objects are walked. */
+function substitute(value: unknown, params: Record<string, unknown>): unknown {
+  if (typeof value === 'string') {
+    return value.replace(PARAM_PATTERN, (_match, name: string) => {
+      const v = params[name];
+      // Per the spec, parameter values are validated against the chain's
+      // parameters schema BEFORE expansion, so `v === undefined` here
+      // means the chain author referenced an undeclared parameter — the
+      // safest substitution is the empty string (matching the standard
+      // {{...}} convention in n8n/Handlebars).
+      return v === undefined ? '' : String(v);
+    });
+  }
+  if (Array.isArray(value)) return value.map((v) => substitute(v, params));
+  if (value !== null && typeof value === 'object') {
+    const out: Record<string, unknown> = {};
+    for (const [k, v] of Object.entries(value)) out[k] = substitute(v, params);
+    return out;
+  }
+  return value;
+}
+
+/** Rewrite an edge endpoint ref. `ref` is either `<nodeId>` or
+ *  `<nodeId>.<portName>`. Only the nodeId portion is rewritten; the
+ *  portName (if present) is preserved verbatim. Refs that don't match
+ *  a fragment node id pass through unchanged (lets edges to/from
+ *  parent-workflow nodes work via post-splice wiring). */
+function rewriteEdgeRef(
+  ref: string,
+  fragmentNodeIds: ReadonlySet<string>,
+  prefix: string,
+): string {
+  const dotIdx = ref.indexOf('.');
+  const nodeId = dotIdx === -1 ? ref : ref.slice(0, dotIdx);
+  const portPart = dotIdx === -1 ? '' : ref.slice(dotIdx);
+  return fragmentNodeIds.has(nodeId) ? `${prefix}${nodeId}${portPart}` : ref;
+}
+
+/** Compute the per-expansion node-id prefix from the chainId + expansionId.
+ *  The chainId's dots are replaced with underscores so the resulting ids
+ *  remain valid in storage backends that reserve `.` for hierarchical
+ *  keys. */
+function computePrefix(chainId: string, expansionId: string): string {
+  return `${chainId.replace(/\./g, '_')}_${expansionId}_`;
+}
+
+/**
+ * Expand a workflow-chain into a concrete fragment ready to splice into a
+ * parent workflow. Implements steps 3 + 5 + 6 + 8 of the normative
+ * `workflow-chain-packs.md` §"Expansion semantics" flow.
+ *
+ * @throws ChainUnresolvableTypeIdError when any `dag.nodes[].typeId`
+ *   fails the caller's `isTypeIdResolvable` predicate.
+ */
+export function expandChain(chain: WorkflowChain, ctx: ExpansionContext): ExpandedFragment {
+  // Step 3: validate every typeId resolves.
+  for (const node of chain.dag.nodes) {
+    if (!ctx.isTypeIdResolvable(node.typeId)) {
+      throw new ChainUnresolvableTypeIdError(node.typeId, chain.chainId);
+    }
+  }
+
+  const prefix = computePrefix(chain.chainId, ctx.expansionId);
+  const fragmentNodeIds = new Set(chain.dag.nodes.map((n) => n.id));
+  const idMap = new Map<string, string>();
+  for (const id of fragmentNodeIds) idMap.set(id, `${prefix}${id}`);
+
+  // Steps 5 + 6 + 8: substitute placeholders, rewrite ids, propagate capabilities.
+  const expandedNodes = chain.dag.nodes.map((n) => {
+    const out: ExpandedFragment['nodes'][number] = {
+      id: `${prefix}${n.id}`,
+      typeId: n.typeId,
+    };
+    if (n.name !== undefined) out.name = n.name;
+    if (n.position !== undefined) out.position = n.position;
+    if (n.config !== undefined) {
+      out.config = substitute(n.config, ctx.params) as Record<string, unknown>;
+    }
+    if (n.inputs !== undefined) {
+      out.inputs = substitute(n.inputs, ctx.params) as Record<string, unknown>;
+    }
+    if (chain.capabilities && chain.capabilities.length > 0) {
+      out.capabilities = [...chain.capabilities];
+    }
+    return out;
+  });
+
+  const expandedEdges = (chain.dag.edges ?? []).map((e) => {
+    const out: ExpandedFragment['edges'][number] = {
+      from: rewriteEdgeRef(e.from, fragmentNodeIds, prefix),
+      to: rewriteEdgeRef(e.to, fragmentNodeIds, prefix),
+    };
+    if (e.condition !== undefined) out.condition = e.condition;
+    return out;
+  });
+
+  return { nodes: expandedNodes, edges: expandedEdges, idMap };
+}