@openwop/openwop-conformance 1.4.0 → 1.6.0

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

package/src/scenarios/auth-saml-profile.test.ts

@@ -0,0 +1,119 @@
+/**
+ * auth-saml-profile — RFC 0050: openwop-auth-saml profile.
+ *
+ * Status: DRAFT. RFC 0050 (SAML / SCIM enterprise identity profiles) is
+ * `Draft`. The profile is documented in `auth-profiles.md`
+ * §`openwop-auth-saml` and reserved in `capabilities.auth.profiles`.
+ *
+ * Capability shape runs unconditionally when the profile is advertised.
+ * The assertion-validation behavior (1 positive + ≥6 negatives: bad
+ * signature, `alg:none`, absent signature, `NotOnOrAfter` expiry,
+ * `NotBefore` not-yet-valid, signature-wrapping) is opt-in via
+ * `OPENWOP_TEST_SAML_IDP_URL` (operator-supplied synthetic IdP), because
+ * a deterministic XML-DSig signer harness isn't bundled yet — follows the
+ * `auth-mtls.test.ts` opt-in precedent. Soft-skips otherwise.
+ *
+ * @see RFCS/0050-saml-scim-enterprise-identity-profiles.md
+ * @see spec/v1/auth-profiles.md §`openwop-auth-saml`
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver } from '../lib/driver.js';
+import { createSyntheticSamlIdp, type SamlVariant } from '../lib/saml-idp.js';
+
+const SAML_PROFILE = 'openwop-auth-saml';
+
+interface DiscoveryAuth {
+  profiles?: string[];
+}
+
+interface DiscoveryDoc {
+  capabilities?: { auth?: DiscoveryAuth };
+  extensions?: { auth?: DiscoveryAuth };
+}
+
+async function readProfiles(): Promise<string[] | null> {
+  const res = await driver.get('/.well-known/openwop');
+  const body = res.json as DiscoveryDoc | undefined;
+  return body?.capabilities?.auth?.profiles ?? body?.extensions?.auth?.profiles ?? null;
+}
+
+describe('auth-saml-profile: advertisement shape (RFC 0050)', () => {
+  it('auth.profiles, when present, is an array of non-empty strings', async () => {
+    const profiles = await readProfiles();
+    if (profiles === null) return; // host advertises no auth profiles
+    expect(
+      Array.isArray(profiles),
+      driver.describe('auth-profiles.md §Discovery', 'capabilities.auth.profiles MUST be an array'),
+    ).toBe(true);
+    for (const p of profiles) {
+      expect(typeof p === 'string' && p.length > 0).toBe(true);
+    }
+  });
+
+  it('claims openwop-auth-saml as a well-formed profile id when advertised', async () => {
+    const profiles = await readProfiles();
+    if (profiles === null || !profiles.includes(SAML_PROFILE)) return; // profile not claimed
+    expect(
+      profiles.includes(SAML_PROFILE),
+      driver.describe('RFC 0050 §A', 'openwop-auth-saml MUST appear verbatim in capabilities.auth.profiles when claimed'),
+    ).toBe(true);
+  });
+});
+
+describe('auth-saml-profile: assertion validation (RFC 0050 §A — opt-in)', () => {
+  const idpUrl = process.env.OPENWOP_TEST_SAML_IDP_URL;
+
+  it('rejects an `alg:none` / unsigned assertion (synthetic IdP required)', async () => {
+    const profiles = await readProfiles();
+    if (profiles === null || !profiles.includes(SAML_PROFILE)) return; // capability-gated
+    if (idpUrl === undefined || idpUrl.length === 0) return; // opt-in: synthetic-IdP harness not provided
+    // With a synthetic IdP, an `alg:none`/unsigned assertion presented to the
+    // host's SAML ACS MUST be rejected with `unauthenticated`.
+    const res = await driver.post('/v1/host/sample/auth/saml/validate', { idpUrl, variant: 'alg-none' });
+    if (res.status === 404) return; // seam unwired
+    expect(
+      res.status,
+      driver.describe('RFC 0050 §A', 'an `alg:none`/unsigned SAML assertion MUST be rejected (non-2xx)'),
+    ).toBeGreaterThanOrEqual(400);
+  });
+});
+
+describe('category: auth-saml synthetic-IdP reference suite (RFC 0050 §A)', () => {
+  // Server-free: the bundled synthetic IdP (conformance/src/lib/saml-idp.ts)
+  // mints a valid assertion + the 6 negative variants, and its verify()
+  // implements the RFC 0050 §A MUST list. This proves each negative is
+  // detectably malformed and gives the suite a reference SAML validator.
+  // A host's real ACS validates the SAME assertions over the
+  // `auth/saml/validate` seam (gated above on OPENWOP_TEST_SAML_IDP_URL).
+  const idp = createSyntheticSamlIdp();
+
+  it('publishes a PEM signing certificate', () => {
+    expect(idp.certificatePem).toContain('BEGIN PUBLIC KEY');
+  });
+
+  it('accepts a valid signed, in-window, non-wrapped assertion', () => {
+    const r = idp.verify(idp.mint('valid'));
+    expect(r.valid, `expected valid; got reason=${r.reason}`).toBe(true);
+  });
+
+  const negatives: ReadonlyArray<[Exclude<SamlVariant, 'valid'>, string]> = [
+    ['alg-none', 'alg-none'],
+    ['unsigned', 'unsigned'],
+    ['bad-signature', 'bad-signature'],
+    ['expired', 'expired'],
+    ['not-yet-valid', 'not-yet-valid'],
+    ['signature-wrapping', 'signature-wrapping'],
+  ];
+
+  for (const [variant, expectedReason] of negatives) {
+    it(`rejects the ${variant} assertion (RFC 0050 §A MUST)`, () => {
+      const r = idp.verify(idp.mint(variant));
+      expect(r.valid, `${variant} MUST be rejected`).toBe(false);
+      expect(
+        r.reason,
+        `${variant} MUST be rejected for the ${expectedReason} reason`,
+      ).toBe(expectedReason);
+    });
+  }
+});

package/src/scenarios/auth-scim-profile.test.ts

@@ -0,0 +1,65 @@
+/**
+ * auth-scim-profile — RFC 0050: openwop-auth-scim profile.
+ *
+ * Status: DRAFT. RFC 0050 (SAML / SCIM enterprise identity profiles) is
+ * `Draft`. The profile is documented in `auth-profiles.md`
+ * §`openwop-auth-scim` and reserved in `capabilities.auth.profiles`.
+ *
+ * Capability shape runs unconditionally when the profile is advertised.
+ * The provisioning roundtrip (SCIM user+group → RFC 0048 principal +
+ * RFC 0049 role; deactivate ⇒ subsequent deny) is opt-in via
+ * `OPENWOP_TEST_SCIM_URL` (operator-supplied SCIM endpoint), following the
+ * `auth-mtls.test.ts` opt-in precedent. Soft-skips otherwise.
+ *
+ * @see RFCS/0050-saml-scim-enterprise-identity-profiles.md
+ * @see spec/v1/auth-profiles.md §`openwop-auth-scim`
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver } from '../lib/driver.js';
+
+const SCIM_PROFILE = 'openwop-auth-scim';
+
+interface DiscoveryAuth {
+  profiles?: string[];
+}
+
+interface DiscoveryDoc {
+  capabilities?: { auth?: DiscoveryAuth };
+  extensions?: { auth?: DiscoveryAuth };
+}
+
+async function readProfiles(): Promise<string[] | null> {
+  const res = await driver.get('/.well-known/openwop');
+  const body = res.json as DiscoveryDoc | undefined;
+  return body?.capabilities?.auth?.profiles ?? body?.extensions?.auth?.profiles ?? null;
+}
+
+describe('auth-scim-profile: advertisement shape (RFC 0050)', () => {
+  it('claims openwop-auth-scim as a well-formed profile id when advertised', async () => {
+    const profiles = await readProfiles();
+    if (profiles === null || !profiles.includes(SCIM_PROFILE)) return; // profile not claimed
+    expect(
+      profiles.includes(SCIM_PROFILE),
+      driver.describe('RFC 0050 §B', 'openwop-auth-scim MUST appear verbatim in capabilities.auth.profiles when claimed'),
+    ).toBe(true);
+  });
+});
+
+describe('auth-scim-profile: provisioning roundtrip (RFC 0050 §B — opt-in)', () => {
+  const scimUrl = process.env.OPENWOP_TEST_SCIM_URL;
+
+  it('provisions a SCIM user → principal (SCIM endpoint required)', async () => {
+    const profiles = await readProfiles();
+    if (profiles === null || !profiles.includes(SCIM_PROFILE)) return; // capability-gated
+    if (scimUrl === undefined || scimUrl.length === 0) return; // opt-in: SCIM endpoint not provided
+    // A SCIM POST /Users against the operator-supplied endpoint MUST upsert a
+    // principal the host can subsequently resolve.
+    const res = await driver.post('/v1/host/sample/auth/scim/provision', { scimUrl, op: 'create-user' });
+    if (res.status === 404) return; // seam unwired
+    expect(
+      res.status,
+      driver.describe('RFC 0050 §B', 'a SCIM user provisioning MUST succeed (2xx) and upsert an RFC 0048 principal'),
+    ).toBeLessThan(400);
+  });
+});

package/src/scenarios/authorization-fail-closed.test.ts

@@ -0,0 +1,80 @@
+/**
+ * authorization-fail-closed — RFC 0049 §C invariant verification.
+ *
+ * Status: DRAFT. RFC 0049 (RBAC scopes & authorization decisions) is `Draft`.
+ * Backs the SECURITY invariant `authorization-fail-closed`.
+ *
+ * Capability-gated: skips when the host does not advertise
+ * `capabilities.authorization.supported = true`.
+ *
+ * What this scenario asserts:
+ *   1. Advertisement shape — when authorization is supported, `failClosed`
+ *      (when present) is exactly `true` (RFC 0049 §C).
+ *   2. Fail-closed MUST-NOT — when the host exposes the optional
+ *      `POST /v1/host/sample/authorization/decide` test seam, a decision for
+ *      a principal with an absent/unseeded role MUST resolve to
+ *      `allowed: false`. The host MUST NOT default-allow under any error
+ *      condition.
+ *
+ * Hosts without the seam soft-skip the behavioral probe (404).
+ *
+ * @see RFCS/0049-rbac-scopes-and-authorization-decisions.md
+ * @see SECURITY/invariants.yaml id: authorization-fail-closed
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver } from '../lib/driver.js';
+
+interface DiscoveryAuthorization {
+  supported?: boolean;
+  failClosed?: boolean;
+}
+
+interface DiscoveryDoc {
+  capabilities?: {
+    authorization?: DiscoveryAuthorization;
+  };
+}
+
+async function readAuthorization(): Promise<DiscoveryAuthorization | null> {
+  const res = await driver.get('/.well-known/openwop');
+  const body = res.json as DiscoveryDoc | undefined;
+  return body?.capabilities?.authorization ?? null;
+}
+
+describe('authorization-fail-closed: advertisement shape (RFC 0049 §C)', () => {
+  it('failClosed is exactly true when authorization is supported', async () => {
+    const authz = await readAuthorization();
+    if (!authz?.supported || authz.failClosed === undefined) return;
+    expect(
+      authz.failClosed,
+      driver.describe('RFC 0049 §C', 'capabilities.authorization.failClosed MUST be `true`'),
+    ).toBe(true);
+  });
+});
+
+describe('authorization-fail-closed: absent/unseeded role MUST deny (RFC 0049 §C)', () => {
+  it('a decision for an unseeded-role principal resolves allowed=false', async () => {
+    const authz = await readAuthorization();
+    if (!authz?.supported) return; // capability-gated
+
+    // Seam contract: request an authorization decision for a principal whose
+    // role is absent/unseeded. The host MUST fail closed.
+    const res = await driver.post('/v1/host/sample/authorization/decide', {
+      principal: 'conformance-unseeded-principal',
+      action: 'runs:cancel',
+      resource: 'run-conformance-probe',
+    });
+    // 404 from a host that hasn't wired the seam is a soft-skip.
+    if (res.status === 404) return;
+
+    const decision = res.json as { allowed?: boolean } | undefined;
+    expect(
+      decision?.allowed,
+      driver.describe(
+        'SECURITY/invariants.yaml authorization-fail-closed',
+        'an absent/unseeded role MUST deny (allowed=false); the host MUST NOT default-allow',
+      ),
+    ).toBe(false);
+  });
+});

package/src/scenarios/authorization-roles-shape.test.ts

@@ -0,0 +1,83 @@
+/**
+ * authorization-roles-shape — RFC 0049 §A advertisement-shape verification.
+ *
+ * Status: DRAFT. RFC 0049 (RBAC scopes & authorization decisions) is `Draft`.
+ * The `capabilities.authorization` block has landed in
+ * `schemas/capabilities.schema.json`.
+ *
+ * Always runs (shape-only): when the host advertises
+ * `capabilities.authorization`, its fields MUST be well-formed.
+ *
+ * What this scenario asserts:
+ *   1. `capabilities.authorization` is either absent or a well-formed object.
+ *   2. When `supported: true`: `failClosed` (when present) is exactly `true`
+ *      (RFC 0049 §C), and every `roles[]` entry has a non-empty `role` + a
+ *      `scopes` array (RFC 0049 §A).
+ *
+ * @see RFCS/0049-rbac-scopes-and-authorization-decisions.md
+ * @see spec/v1/auth.md §"Role-based authorization (RFC 0049)"
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver } from '../lib/driver.js';
+
+interface DiscoveryRole {
+  role?: string;
+  scopes?: string[];
+}
+
+interface DiscoveryAuthorization {
+  supported?: boolean;
+  failClosed?: boolean;
+  roles?: DiscoveryRole[];
+}
+
+interface DiscoveryDoc {
+  capabilities?: {
+    authorization?: DiscoveryAuthorization;
+  };
+}
+
+async function readAuthorization(): Promise<DiscoveryAuthorization | null> {
+  const res = await driver.get('/.well-known/openwop');
+  const body = res.json as DiscoveryDoc | undefined;
+  return body?.capabilities?.authorization ?? null;
+}
+
+describe('authorization-roles-shape: advertisement shape (RFC 0049 §A)', () => {
+  it('capabilities.authorization is either absent or well-formed', async () => {
+    const authz = await readAuthorization();
+    if (authz === null) return; // host doesn't advertise authorization at all
+    expect(
+      typeof authz.supported,
+      driver.describe(
+        'capabilities.schema.json §authorization',
+        'capabilities.authorization.supported MUST be a boolean when authorization is advertised',
+      ),
+    ).toBe('boolean');
+  });
+
+  it('failClosed, when present, is exactly true (RFC 0049 §C)', async () => {
+    const authz = await readAuthorization();
+    if (!authz?.supported || authz.failClosed === undefined) return;
+    expect(
+      authz.failClosed,
+      driver.describe('RFC 0049 §C', 'capabilities.authorization.failClosed MUST be `true` (fail-closed)'),
+    ).toBe(true);
+  });
+
+  it('every advertised role has a non-empty role name + a scopes array', async () => {
+    const authz = await readAuthorization();
+    if (!authz?.supported || authz.roles === undefined) return;
+    for (const entry of authz.roles) {
+      expect(
+        typeof entry.role === 'string' && entry.role.length > 0,
+        driver.describe('RFC 0049 §A', 'each capabilities.authorization.roles[] entry MUST declare a non-empty role'),
+      ).toBe(true);
+      expect(
+        Array.isArray(entry.scopes),
+        driver.describe('RFC 0049 §A', 'each role MUST declare a scopes array'),
+      ).toBe(true);
+    }
+  });
+});