@openwop/openwop-conformance 1.5.0 → 1.6.0

package/schemas/run-event-payloads.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://openwop.dev/spec/v1/run-event-payloads.schema.json",
   "title": "RunEventPayloads",
-  "description": "Per-RunEventType payload schemas. The base RunEventDoc shape (run-event.schema.json) leaves `payload` permissive for forward-compat. This schema defines the canonical payload contract for each known RunEventType. Consumers MAY pin strict payload validation via `$defs.<typeId>` and `ajv.validate(schema.$defs[event.type], event.payload)`. Unknown event types MUST be tolerated (no $defs match → fold best-effort).\n\n64 variants from `run-event.schema.json#$defs.RunEventType` are covered, grouped into ~20 shape families with shared $defs. Naming convention: camelCase keys mirror dotted RunEventType names (e.g., `run.started` → `runStarted`).",
+  "description": "Per-RunEventType payload schemas. The base RunEventDoc shape (run-event.schema.json) leaves `payload` permissive for forward-compat. This schema defines the canonical payload contract for each known RunEventType. Consumers MAY pin strict payload validation via `$defs.<typeId>` and `ajv.validate(schema.$defs[event.type], event.payload)`. Unknown event types MUST be tolerated (no $defs match → fold best-effort).\n\n71 variants from `run-event.schema.json#$defs.RunEventType` are covered, grouped into ~20 shape families with shared $defs. Naming convention: camelCase keys mirror dotted RunEventType names (e.g., `run.started` → `runStarted`).",
   "type": "object",
   "$defs": {
     "_typeIndex": {
@@ -18,6 +18,7 @@
         "run.paused":                { "$ref": "#/$defs/runPaused" },
         "run.resumed":               { "$ref": "#/$defs/runResumed" },
         "run.restored-from-snapshot":{ "$ref": "#/$defs/runRestoredFromSnapshot" },
+        "run.dead_lettered":         { "$ref": "#/$defs/runDeadLettered" },
         "node.started":              { "$ref": "#/$defs/nodeStarted" },
         "node.completed":            { "$ref": "#/$defs/nodeCompleted" },
         "node.failed":               { "$ref": "#/$defs/nodeFailed" },
@@ -29,6 +30,9 @@
         "node.cancelled":            { "$ref": "#/$defs/nodeCancelled" },
         "approval.requested":        { "$ref": "#/$defs/approvalRequested" },
         "approval.received":         { "$ref": "#/$defs/approvalReceived" },
+        "approval.granted":          { "$ref": "#/$defs/approvalGranted" },
+        "approval.rejected":         { "$ref": "#/$defs/approvalRejected" },
+        "approval.overridden":       { "$ref": "#/$defs/approvalOverridden" },
         "clarification.requested":   { "$ref": "#/$defs/clarificationRequested" },
         "clarification.resolved":    { "$ref": "#/$defs/clarificationResolved" },
         "interrupt.requested":       { "$ref": "#/$defs/interruptRequested" },
@@ -73,7 +77,48 @@
         "conversation.closed":       { "$ref": "#/$defs/conversationClosed" },
         "memory.compacted":          { "$ref": "#/$defs/memoryCompacted" },
         "core.workflowChain.event":  { "$ref": "#/$defs/coreWorkflowChainEvent" },
-        "core.workflowChain.confidence-escalated": { "$ref": "#/$defs/coreWorkflowChainConfidenceEscalated" }
+        "core.workflowChain.confidence-escalated": { "$ref": "#/$defs/coreWorkflowChainConfidenceEscalated" },
+        "connector.authorized":      { "$ref": "#/$defs/connectorAuthorized" },
+        "connector.auth_expired":    { "$ref": "#/$defs/connectorAuthExpired" },
+        "authorization.decided":     { "$ref": "#/$defs/authorizationDecided" }
+      }
+    },
+
+    "authorizationDecided": {
+      "description": "RFC 0049 — emitted on a role-based authorization decision (allow or deny). Redaction-safe: `principal` is an opaque RFC 0048 id; `reason` carries no credential material. Every deny SHOULD be emitted and SHOULD feed the audit log (RFC 0009/0010). MUST NOT be emitted unless `capabilities.authorization.supported: true`.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["principal", "action", "resource", "allowed"],
+      "properties": {
+        "principal": { "type": "string", "minLength": 1, "description": "Opaque RFC 0048 principal id — never PII." },
+        "action": { "type": "string", "minLength": 1, "description": "The attempted action, e.g. `runs:cancel`." },
+        "resource": { "type": "string", "minLength": 1, "description": "The target, e.g. a runId or workflowId." },
+        "allowed": { "type": "boolean" },
+        "reason": { "type": "string", "description": "Human-readable, redaction-safe — no credential material." }
+      }
+    },
+
+    "connectorAuthorized": {
+      "description": "RFC 0047 — emitted when the host acquires (or re-authorizes) a third-party OAuth token on a user's behalf via the `host.oauth` flow. Redaction-safe: carries the credential REFERENCE (RFC 0046), never token material. MUST NOT be emitted unless `capabilities.oauth.supported: true`.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["provider", "credentialRef"],
+      "properties": {
+        "provider": { "type": "string", "minLength": 1, "description": "Provider id, matching an advertised `capabilities.oauth.providers[].id` (e.g. `slack`, `google`)." },
+        "credentialRef": { "type": "string", "minLength": 1, "description": "Opaque RFC 0046 credential reference where the acquired token is stored. NEVER the token itself." },
+        "scopes": { "type": "array", "items": { "type": "string" }, "description": "Scopes granted for the acquired token." }
+      }
+    },
+
+    "connectorAuthExpired": {
+      "description": "RFC 0047 — emitted when a stored OAuth token's refresh fails terminally (revoked/expired refresh token). Redaction-safe: no token material. MUST NOT be emitted unless `capabilities.oauth.supported: true`.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["provider", "credentialRef"],
+      "properties": {
+        "provider": { "type": "string", "minLength": 1, "description": "Provider id, matching an advertised `capabilities.oauth.providers[].id`." },
+        "credentialRef": { "type": "string", "minLength": 1, "description": "Opaque RFC 0046 credential reference for the expired token." },
+        "reason": { "type": "string", "description": "Redaction-safe human-readable reason (e.g. `refresh_token_revoked`)." }
       }
     },
 
@@ -205,6 +250,17 @@
         "inputs":      { "$ref": "#/$defs/_inputsObject" },
         "transport":   { "type": "string", "enum": ["rest", "mcp", "a2a", "ui"] },
         "engineVersion":  { "type": "string" },
+        "owner": {
+          "type": "object",
+          "description": "RFC 0048. Redaction-safe echo of the run's owning identity triple (matches `RunSnapshot.owner`). Optional; single-tenant hosts omit it.",
+          "required": ["tenant"],
+          "properties": {
+            "tenant": { "type": "string", "minLength": 1 },
+            "workspace": { "type": "string", "minLength": 1 },
+            "principal": { "type": "string", "minLength": 1 }
+          },
+          "additionalProperties": false
+        },
         "tags":     { "type": "array", "items": { "type": "string" } },
         "metadata": { "type": "object" }
       },
@@ -272,6 +328,19 @@
       "additionalProperties": true
     },
 
+    "runDeadLettered": {
+      "description": "RFC 0053 — emitted when a run/node exhausts its retry policy (RFC 0009) and is routed to the durable dead-letter sink. The run remains fork-eligible (RFC 0011) for `capabilities.deadLetter.retentionDays`. Redaction-safe: `reason` carries no credential material. MUST NOT be emitted unless `capabilities.deadLetter.supported: true`.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["runId", "reason", "attempts"],
+      "properties": {
+        "runId": { "type": "string", "minLength": 1 },
+        "nodeId": { "type": "string", "description": "The node whose retry exhaustion dead-lettered the run; absent for run-level failures." },
+        "reason": { "type": "string", "minLength": 1, "description": "Redaction-safe terminal-failure reason." },
+        "attempts": { "type": "integer", "minimum": 1, "description": "Total attempts made before dead-lettering." }
+      }
+    },
+
     "nodeStarted": {
       "type": "object",
       "description": "Emitted when a node begins execution.",
@@ -419,6 +488,39 @@
       },
       "additionalProperties": true
     },
+    "approvalGranted": {
+      "description": "RFC 0051 — emitted when an authorized principal grants a `core.openwop.governance.approvalGate`. Redaction-safe: `principal` is an opaque RFC 0048 id. MUST NOT be emitted unless the gate node is registered (peerDependency `authorization: 'supported'`).",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["gateId", "principal"],
+      "properties": {
+        "gateId": { "type": "string", "minLength": 1, "description": "Identifier of the approval gate node." },
+        "principal": { "type": "string", "minLength": 1, "description": "Opaque RFC 0048 principal id of the granting actor." },
+        "quorumProgress": { "type": "object", "additionalProperties": false, "properties": { "granted": { "type": "integer", "minimum": 0 }, "required": { "type": "integer", "minimum": 1 } }, "description": "When the gate requires a quorum: grants accumulated vs required." }
+      }
+    },
+    "approvalRejected": {
+      "description": "RFC 0051 — emitted when an authorized principal rejects an approval gate. The run loops back per the workflow edges (does not terminate by default). Redaction-safe.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["gateId", "principal"],
+      "properties": {
+        "gateId": { "type": "string", "minLength": 1 },
+        "principal": { "type": "string", "minLength": 1, "description": "Opaque RFC 0048 principal id of the rejecting actor." },
+        "reason": { "type": "string", "description": "Redaction-safe human-readable reason." }
+      }
+    },
+    "approvalOverridden": {
+      "description": "RFC 0051 — emitted when a role-gated `override` path bypasses the gate (e.g. owner force-publish). MUST feed the audit log (RFC 0009/0010). Redaction-safe.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["gateId", "principal", "reason"],
+      "properties": {
+        "gateId": { "type": "string", "minLength": 1 },
+        "principal": { "type": "string", "minLength": 1, "description": "Opaque RFC 0048 principal id of the overriding actor (MUST satisfy the override role)." },
+        "reason": { "type": "string", "minLength": 1, "description": "Required, redaction-safe rationale — the audit breadcrumb." }
+      }
+    },
     "clarificationRequested": {
       "type": "object",
       "description": "Legacy kind-specific event for HITL clarification requests.",

package/schemas/run-event.schema.json

@@ -71,6 +71,7 @@
         "run.paused",
         "run.resumed",
         "run.restored-from-snapshot",
+        "run.dead_lettered",
         "node.started",
         "node.completed",
         "node.failed",
@@ -82,6 +83,9 @@
         "node.cancelled",
         "approval.requested",
         "approval.received",
+        "approval.granted",
+        "approval.rejected",
+        "approval.overridden",
         "clarification.requested",
         "clarification.resolved",
         "interrupt.requested",
@@ -126,7 +130,10 @@
         "conversation.closed",
         "memory.compacted",
         "core.workflowChain.event",
-        "core.workflowChain.confidence-escalated"
+        "core.workflowChain.confidence-escalated",
+        "connector.authorized",
+        "connector.auth_expired",
+        "authorization.decided"
       ]
     }
   }

package/schemas/run-snapshot.schema.json

@@ -32,6 +32,17 @@
       ],
       "description": "Current run state. `waiting-external` MUST be used when the suspended interrupt's `kind` is `external-event` per `interrupt-profiles.md §openwop-interrupt-external-event` — distinguishes external-event waits from HITL waits at the wire level. Forward-compat: future statuses MAY be added; readers SHOULD treat unknown values as terminal-unknown rather than throw."
     },
+    "owner": {
+      "type": "object",
+      "description": "RFC 0048. The identity triple that owns this run. Redaction-safe — `principal` is an opaque identifier, never PII or credential material. Optional: single-tenant hosts omit it. A principal scoped to one `workspace` MUST NOT read a run owned by another (`run_forbidden`).",
+      "required": ["tenant"],
+      "properties": {
+        "tenant": { "type": "string", "minLength": 1, "description": "Top-level isolation boundary." },
+        "workspace": { "type": "string", "minLength": 1, "description": "Optional sub-tenant within the tenant (RFC 0048 workspace)." },
+        "principal": { "type": "string", "minLength": 1, "description": "Acting identity (user or agent) — opaque id, never PII." }
+      },
+      "additionalProperties": false
+    },
     "currentNodeId": {
       "type": "string",
       "description": "Set when the run is suspended at a specific node (`waiting-approval` / `waiting-input` / `waiting-external`) — identifies which node holds the interrupt."

package/src/lib/behavior-gate.ts

@@ -105,3 +105,54 @@ export function behaviorGate(profileName: string, advertised: boolean): boolean
   );
   return false;
 }
+
+/**
+ * RFC 0042 §D — experimental-tier soft-skip router for capability-gated
+ * scenarios. Wraps `behaviorGate` with an additional tier check.
+ *
+ * Returns true if the scenario should proceed with assertions, false if
+ * it should skip:
+ *   - tier === 'experimental' AND OPENWOP_REQUIRE_EXPERIMENTAL not set → soft-skip
+ *     (the scenario does NOT count toward "Failed" or "Skipped (capability-gated)"
+ *      in the four-bucket taxonomy — a new fifth bucket "Skipped (experimental)"
+ *      SHOULD be tallied by reporters; logged via the dedicated console.warn below.)
+ *   - tier === 'experimental' AND OPENWOP_REQUIRE_EXPERIMENTAL=true → behave as
+ *     stable (hand off to behaviorGate; honor OPENWOP_REQUIRE_BEHAVIOR + opt-out).
+ *   - tier === 'stable' (default) → identical to behaviorGate.
+ *
+ * The `experimentalUntil` ISO-8601 date is logged for telemetry but does NOT
+ * gate behavior — the spec contract is that the wire shape MAY shift before
+ * the date, not that the scenario MUST stop running.
+ */
+export function experimentalGate(
+  profileName: string,
+  advertised: boolean,
+  tier: 'stable' | 'experimental' | undefined,
+  experimentalUntil?: string,
+): boolean {
+  if (tier === 'experimental') {
+    const env = loadEnv();
+    const requireExperimental = process.env.OPENWOP_REQUIRE_EXPERIMENTAL === 'true';
+    if (!requireExperimental) {
+      // eslint-disable-next-line no-console
+      console.warn(
+        `[experimental capability: ${profileName}] host advertises tier='experimental'` +
+          (experimentalUntil ? ` until ${experimentalUntil}` : '') +
+          `; scenario skipped under default mode (set OPENWOP_REQUIRE_EXPERIMENTAL=true to run)`,
+      );
+      return false;
+    }
+    // Strict-mode experimental: hand off to behaviorGate with the standard
+    // advertised+opt-out rules. A host that advertises tier='experimental'
+    // AND opts the profile out via OPENWOP_OPTED_OUT_PROFILES would surface
+    // the standard advertise+opt-out conflict warning from behaviorGate.
+    // Don't strip the env.requireBehavior flag — that's a separate axis.
+    // eslint-disable-next-line no-console
+    console.warn(
+      `[experimental capability: ${profileName}] OPENWOP_REQUIRE_EXPERIMENTAL=true; ` +
+        `running as strict assertion against advertised='${advertised}'`,
+    );
+    void env;
+  }
+  return behaviorGate(profileName, advertised);
+}

package/src/lib/driver.ts

@@ -50,7 +50,19 @@ class OpenWOPDriver {
 
     const fetchInit: RequestInit = { method, headers };
     if (init.body !== undefined) {
-      fetchInit.body = JSON.stringify(init.body);
+      // Buffer / Uint8Array bodies are sent as raw bytes — needed by the
+      // RFC 0025 test-mode publish scenarios so the host's body-shape
+      // check sees the bytes the caller actually wrote (rather than a
+      // JSON-stringified `{"type":"Buffer","data":[...]}` envelope).
+      if (typeof Buffer !== 'undefined' && Buffer.isBuffer(init.body)) {
+        fetchInit.body = new Uint8Array(init.body);
+      } else if (init.body instanceof Uint8Array) {
+        fetchInit.body = init.body;
+      } else if (typeof init.body === 'string') {
+        fetchInit.body = init.body;
+      } else {
+        fetchInit.body = JSON.stringify(init.body);
+      }
     }
     const res = await fetch(url, fetchInit);
 

package/src/lib/saml-idp.ts

@@ -0,0 +1,179 @@
+/**
+ * Synthetic SAML 2.0 IdP for conformance scenarios (RFC 0050).
+ *
+ * Mints SAML assertions — a valid signed one plus the negative variants
+ * the `openwop-auth-saml` profile requires hosts to reject — and exposes
+ * the signing certificate a trusting host configures. Hermetic: uses only
+ * `node:crypto` stdlib (RSA-SHA256), no npm dependencies, no XML library.
+ *
+ * Scope: this harness is a wire-shape + validation-logic reference, NOT a
+ * full XML-DSig stack. It produces a controlled, fixed-shape assertion
+ * template and signs an enveloped digest of it with RSA-SHA256; `verify()`
+ * implements exactly the RFC 0050 §A MUST list (signature present + valid,
+ * `alg:none` rejected, validity window enforced, signature-wrapping
+ * rejected) so the suite can assert each negative variant is detectably
+ * malformed. A host's real SAML ACS validates the same assertions over the
+ * `auth/saml/validate` test seam; sign/verify here are mutually consistent
+ * by construction (the harness owns both the serialization and the digest).
+ *
+ * @see RFCS/0050-saml-scim-enterprise-identity-profiles.md §A
+ * @see spec/v1/auth-profiles.md §`openwop-auth-saml`
+ */
+
+import {
+  createSign,
+  createVerify,
+  createHash,
+  generateKeyPairSync,
+} from 'node:crypto';
+
+/** The assertion variants the conformance suite exercises (1 positive + 6 negatives). */
+export type SamlVariant =
+  | 'valid'
+  | 'alg-none'
+  | 'bad-signature'
+  | 'unsigned'
+  | 'expired'
+  | 'not-yet-valid'
+  | 'signature-wrapping';
+
+export interface SamlVerifyResult {
+  /** True only for a well-formed, signed, in-window, non-wrapped assertion. */
+  readonly valid: boolean;
+  /** Machine-readable rejection cause; `null` when `valid`. */
+  readonly reason:
+    | null
+    | 'unsigned'
+    | 'alg-none'
+    | 'bad-signature'
+    | 'expired'
+    | 'not-yet-valid'
+    | 'signature-wrapping'
+    | 'malformed';
+}
+
+export interface SyntheticSamlIdp {
+  /** PEM signing certificate (public key) the host configures to trust this IdP. */
+  readonly certificatePem: string;
+  /** Mint a SAML assertion of the given variant. */
+  mint(variant: SamlVariant, opts?: { subject?: string }): string;
+  /** Validate an assertion per the RFC 0050 §A MUST list. */
+  verify(assertionXml: string): SamlVerifyResult;
+}
+
+const SIG_ALG_RSA_SHA256 = 'http://www.w3.org/2001/04/xmldsig-more#rsa-sha256';
+const SIG_ALG_NONE = 'http://www.w3.org/2000/09/xmldsig#none';
+
+function digest(input: string): string {
+  return createHash('sha256').update(input, 'utf8').digest('base64');
+}
+
+/** Deterministic canonical form of the signed element: the harness controls
+ * the exact byte string, so sign/verify agree without a full C14N stack. */
+function canonicalAssertion(id: string, subject: string, notBefore: string, notOnOrAfter: string): string {
+  return (
+    `<saml:Assertion ID="${id}" Version="2.0">` +
+    `<saml:Conditions NotBefore="${notBefore}" NotOnOrAfter="${notOnOrAfter}"/>` +
+    `<saml:Subject><saml:NameID>${subject}</saml:NameID></saml:Subject>` +
+    `</saml:Assertion>`
+  );
+}
+
+export function createSyntheticSamlIdp(): SyntheticSamlIdp {
+  const { publicKey, privateKey } = generateKeyPairSync('rsa', { modulusLength: 2048 });
+  const certificatePem = publicKey.export({ format: 'pem', type: 'spki' }).toString();
+
+  function sign(canonical: string): string {
+    return createSign('RSA-SHA256').update(canonical, 'utf8').sign(privateKey, 'base64');
+  }
+
+  function envelope(parts: {
+    id: string;
+    subject: string;
+    notBefore: string;
+    notOnOrAfter: string;
+    sigAlg: string;
+    signatureValue: string | null;
+    refId: string; // the ID the <Reference> points at (≠ id ⇒ wrapping)
+    extraInjected?: string; // an unsigned injected assertion (wrapping attack)
+  }): string {
+    const inner = canonicalAssertion(parts.id, parts.subject, parts.notBefore, parts.notOnOrAfter);
+    const sig =
+      parts.signatureValue === null
+        ? ''
+        : `<ds:Signature>` +
+          `<ds:SignedInfo><ds:SignatureMethod Algorithm="${parts.sigAlg}"/>` +
+          `<ds:Reference URI="#${parts.refId}"><ds:DigestValue>${digest(inner)}</ds:DigestValue></ds:Reference>` +
+          `</ds:SignedInfo><ds:SignatureValue>${parts.signatureValue}</ds:SignatureValue></ds:Signature>`;
+    return `<samlp:Response>${parts.extraInjected ?? ''}${inner.replace('</saml:Assertion>', `${sig}</saml:Assertion>`)}</samlp:Response>`;
+  }
+
+  function mint(variant: SamlVariant, opts?: { subject?: string }): string {
+    const id = 'a-' + variant;
+    const subject = opts?.subject ?? 'user_42@example.com-opaque';
+    const now = Date.now();
+    const iso = (ms: number): string => new Date(ms).toISOString();
+    const past = iso(now - 3_600_000);
+    const future = iso(now + 3_600_000);
+    const canonical = canonicalAssertion(id, subject, past, future);
+
+    switch (variant) {
+      case 'valid':
+        return envelope({ id, subject, notBefore: past, notOnOrAfter: future, sigAlg: SIG_ALG_RSA_SHA256, signatureValue: sign(canonical), refId: id });
+      case 'unsigned':
+        return envelope({ id, subject, notBefore: past, notOnOrAfter: future, sigAlg: SIG_ALG_RSA_SHA256, signatureValue: null, refId: id });
+      case 'alg-none':
+        return envelope({ id, subject, notBefore: past, notOnOrAfter: future, sigAlg: SIG_ALG_NONE, signatureValue: '', refId: id });
+      case 'bad-signature':
+        return envelope({ id, subject, notBefore: past, notOnOrAfter: future, sigAlg: SIG_ALG_RSA_SHA256, signatureValue: Buffer.from('forged').toString('base64'), refId: id });
+      case 'expired': {
+        const c = canonicalAssertion(id, subject, iso(now - 7_200_000), past);
+        return envelope({ id, subject, notBefore: iso(now - 7_200_000), notOnOrAfter: past, sigAlg: SIG_ALG_RSA_SHA256, signatureValue: sign(c), refId: id });
+      }
+      case 'not-yet-valid': {
+        const c = canonicalAssertion(id, subject, future, iso(now + 7_200_000));
+        return envelope({ id, subject, notBefore: future, notOnOrAfter: iso(now + 7_200_000), sigAlg: SIG_ALG_RSA_SHA256, signatureValue: sign(c), refId: id });
+      }
+      case 'signature-wrapping': {
+        // Signature validly covers a benign assertion (refId = benign), but a
+        // second, attacker-injected assertion with a different Subject is what
+        // a naive consumer reads. The signed element ≠ the consumed element.
+        const benign = 'a-benign';
+        const benignCanonical = canonicalAssertion(benign, subject, past, future);
+        const injected = canonicalAssertion(id, 'attacker@evil.example-opaque', past, future);
+        const sig =
+          `<ds:Signature><ds:SignedInfo><ds:SignatureMethod Algorithm="${SIG_ALG_RSA_SHA256}"/>` +
+          `<ds:Reference URI="#${benign}"><ds:DigestValue>${digest(benignCanonical)}</ds:DigestValue></ds:Reference>` +
+          `</ds:SignedInfo><ds:SignatureValue>${sign(benignCanonical)}</ds:SignatureValue></ds:Signature>`;
+        // Consumed (first) assertion carries the signature but is the INJECTED one.
+        return `<samlp:Response>${injected.replace('</saml:Assertion>', `${sig}</saml:Assertion>`)}${benignCanonical}</samlp:Response>`;
+      }
+    }
+  }
+
+  function verify(assertionXml: string): SamlVerifyResult {
+    const sigAlg = /<ds:SignatureMethod Algorithm="([^"]+)"/.exec(assertionXml)?.[1];
+    const sigValue = /<ds:SignatureValue>([^<]*)<\/ds:SignatureValue>/.exec(assertionXml)?.[1];
+    const refId = /<ds:Reference URI="#([^"]+)"/.exec(assertionXml)?.[1];
+    // The consumed assertion is the FIRST <saml:Assertion> in the response.
+    const consumed = /<saml:Assertion ID="([^"]+)"[^>]*>[\s\S]*?<saml:Conditions NotBefore="([^"]+)" NotOnOrAfter="([^"]+)"\/>[\s\S]*?<saml:NameID>([^<]*)<\/saml:NameID>/.exec(assertionXml);
+    if (consumed === null) return { valid: false, reason: 'malformed' };
+    const [, consumedId, notBefore, notOnOrAfter, subject] = consumed;
+
+    if (sigValue === undefined || sigAlg === undefined) return { valid: false, reason: 'unsigned' };
+    if (sigAlg === SIG_ALG_NONE) return { valid: false, reason: 'alg-none' };
+    // Anti-wrapping: the signature MUST reference the consumed assertion.
+    if (refId !== consumedId) return { valid: false, reason: 'signature-wrapping' };
+
+    const canonical = canonicalAssertion(consumedId, subject, notBefore, notOnOrAfter);
+    const ok = createVerify('RSA-SHA256').update(canonical, 'utf8').verify(publicKey, sigValue, 'base64');
+    if (!ok) return { valid: false, reason: 'bad-signature' };
+
+    const now = Date.now();
+    if (now < Date.parse(notBefore)) return { valid: false, reason: 'not-yet-valid' };
+    if (now >= Date.parse(notOnOrAfter)) return { valid: false, reason: 'expired' };
+    return { valid: true, reason: null };
+  }
+
+  return { certificatePem, mint, verify };
+}

package/src/scenarios/approval-gate-events.test.ts

@@ -0,0 +1,61 @@
+/**
+ * approval-gate-events — RFC 0051 §B event-shape verification.
+ *
+ * Status: DRAFT. RFC 0051 (approval & deployment-gate primitive) is `Draft`.
+ * The `approval.granted` / `approval.rejected` / `approval.overridden` event
+ * payloads have landed in `schemas/run-event-payloads.schema.json` (+ the
+ * `RunEventType` enum).
+ *
+ * Server-free schema validation of the three governance events:
+ *   - granted: requires `{ gateId, principal }`; optional `quorumProgress`.
+ *   - rejected: requires `{ gateId, principal }`; optional `reason`.
+ *   - overridden: requires `{ gateId, principal, reason }` (reason mandatory —
+ *     the audit breadcrumb).
+ *   - each rejects unknown properties (additionalProperties:false).
+ *
+ * @see RFCS/0051-approval-deployment-gate-primitive.md
+ * @see spec/v1/interrupt-profiles.md §`core.openwop.governance.approvalGate`
+ */
+
+import { describe, it, expect } from 'vitest';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import Ajv2020 from 'ajv/dist/2020.js';
+import { SCHEMAS_DIR } from '../lib/paths.js';
+
+interface PayloadsSchema {
+  $schema: string;
+  $defs: Record<string, Record<string, unknown>>;
+}
+
+const payloads = JSON.parse(
+  readFileSync(join(SCHEMAS_DIR, 'run-event-payloads.schema.json'), 'utf8'),
+) as PayloadsSchema;
+
+function compile(defName: string) {
+  const ajv = new Ajv2020({ allErrors: true, strict: false });
+  return ajv.compile({ $schema: payloads.$schema, ...payloads.$defs[defName] });
+}
+
+describe('category: approval-gate governance events (RFC 0051 §B)', () => {
+  it('approval.granted requires gateId + principal; quorumProgress optional', () => {
+    const v = compile('approvalGranted');
+    expect(v({ gateId: 'g1', principal: 'user_1' }), JSON.stringify(v.errors)).toBe(true);
+    expect(v({ gateId: 'g1', principal: 'user_1', quorumProgress: { granted: 1, required: 2 } })).toBe(true);
+    expect(v({ gateId: 'g1' })).toBe(false); // missing principal
+    expect(v({ gateId: 'g1', principal: 'user_1', role: 'admin' })).toBe(false); // unknown prop
+  });
+
+  it('approval.rejected requires gateId + principal; reason optional', () => {
+    const v = compile('approvalRejected');
+    expect(v({ gateId: 'g1', principal: 'user_1' }), JSON.stringify(v.errors)).toBe(true);
+    expect(v({ gateId: 'g1', principal: 'user_1', reason: 'incomplete' })).toBe(true);
+    expect(v({ principal: 'user_1' })).toBe(false); // missing gateId
+  });
+
+  it('approval.overridden requires gateId + principal + reason (audit breadcrumb)', () => {
+    const v = compile('approvalOverridden');
+    expect(v({ gateId: 'g1', principal: 'owner_1', reason: 'emergency publish' }), JSON.stringify(v.errors)).toBe(true);
+    expect(v({ gateId: 'g1', principal: 'owner_1' })).toBe(false); // reason MUST be present
+  });
+});

package/src/scenarios/approval-gate-flow.test.ts

@@ -0,0 +1,68 @@
+/**
+ * approval-gate-flow — RFC 0051 §A behavioral verification.
+ *
+ * Status: DRAFT. RFC 0051 (approval & deployment-gate primitive) is `Draft`.
+ *
+ * Capability-gated: the `core.openwop.governance.approvalGate` node requires
+ * a host advertising `capabilities.authorization.supported = true`
+ * (peerDependency `authorization: 'supported'`). Skips otherwise.
+ *
+ * What this scenario asserts (via the optional
+ * `POST /v1/host/sample/governance/approval-gate` seam):
+ *   1. Unauthorized principal — a principal lacking `requiredRole`/`requiredScope`
+ *      is denied; the gate does NOT release (fail-closed, RFC 0049 §C).
+ *   2. Override is audited — taking the role-gated `override` path returns an
+ *      `approval.overridden` event whose `reason` is present.
+ *
+ * Hosts without the seam soft-skip the behavioral probes (404).
+ *
+ * @see RFCS/0051-approval-deployment-gate-primitive.md
+ * @see spec/v1/interrupt-profiles.md §`core.openwop.governance.approvalGate`
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver } from '../lib/driver.js';
+
+interface DiscoveryDoc {
+  capabilities?: { authorization?: { supported?: boolean } };
+}
+
+async function authorizationSupported(): Promise<boolean> {
+  const res = await driver.get('/.well-known/openwop');
+  return (res.json as DiscoveryDoc | undefined)?.capabilities?.authorization?.supported === true;
+}
+
+describe('approval-gate-flow: role-gated, audited approval (RFC 0051 §A)', () => {
+  it('an unauthorized principal does NOT release the gate (fail-closed)', async () => {
+    if (!(await authorizationSupported())) return; // capability-gated
+    const res = await driver.post('/v1/host/sample/governance/approval-gate', {
+      scenario: 'unauthorized-grant',
+      principal: 'conformance-unauthorized-principal',
+    });
+    if (res.status === 404) return; // seam unwired — soft-skip
+    const body = res.json as { released?: boolean } | undefined;
+    expect(
+      body?.released,
+      driver.describe('RFC 0051 §A', 'an unauthorized principal MUST NOT release the gate (fail-closed)'),
+    ).toBe(false);
+  });
+
+  it('the override path emits an audited approval.overridden with a reason', async () => {
+    if (!(await authorizationSupported())) return; // capability-gated
+    const res = await driver.post('/v1/host/sample/governance/approval-gate', {
+      scenario: 'override',
+      principal: 'conformance-owner-principal',
+      reason: 'conformance emergency publish',
+    });
+    if (res.status === 404) return; // seam unwired — soft-skip
+    const body = res.json as { event?: { type?: string; payload?: { reason?: string } } } | undefined;
+    expect(
+      body?.event?.type,
+      driver.describe('RFC 0051 §B', 'taking the override path MUST emit approval.overridden'),
+    ).toBe('approval.overridden');
+    expect(
+      typeof body?.event?.payload?.reason === 'string' && body.event.payload.reason.length > 0,
+      driver.describe('RFC 0051 §B', 'approval.overridden MUST carry a non-empty reason (the audit breadcrumb)'),
+    ).toBe(true);
+  });
+});