@openwop/openwop-conformance 2.35.0 → 2.36.0

package/src/lib/certification-bundle-v3.ts

@@ -163,11 +163,25 @@ export interface V3Verdict {
 
 const OPT_OUT_ROW = 'openwop.profile.';
 /** The opt-outs a bundle's signed rows record. */
+/**
+ * 2.35.1. The 2.35.0 version read only `openwop.profile.<name>` rows — which
+ * never reach a bundle — so on MyndHyve's real bundle (four declared opt-outs)
+ * it derived NOTHING, and `opted-out-but-advertised` could not fire: a rule
+ * pinned only by synthetic self-test rows. The name now rides on the signed
+ * per-test rows' detail (`…OPENWOP_OPTED_OUT_PROFILES: <name>`); both carriers
+ * are read. A bundle cut before 2.35.1 carries no names and derives an empty set.
+ */
+const OPT_OUT_DETAIL = /OPENWOP_OPTED_OUT_PROFILES: ([a-z][A-Za-z0-9_.-]*)/;
 export function optedOutFromRows(rows: ReadonlyArray<{ readonly id: string; readonly result: string; readonly detail?: string }>): string[] {
-  return rows
-    .filter((r) => r.id.startsWith(OPT_OUT_ROW) && r.result === 'skipped' && (r.detail ?? '').includes('OPENWOP_OPTED_OUT_PROFILES'))
-    .map((r) => r.id.slice(OPT_OUT_ROW.length))
-    .sort();
+  const names = new Set<string>();
+  for (const r of rows) {
+    if (r.result !== 'skipped') continue;
+    const d = r.detail ?? '';
+    if (r.id.startsWith(OPT_OUT_ROW) && d.includes('OPENWOP_OPTED_OUT_PROFILES')) names.add(r.id.slice(OPT_OUT_ROW.length));
+    const m = OPT_OUT_DETAIL.exec(d);
+    if (m) names.add(m[1] as string);
+  }
+  return [...names].sort();
 }
 
 export function verifyBundleV3(bundle: BundleV3, opts: VerifyV3Options = {}): V3Verdict {

package/src/lib/localized-content.ts

@@ -0,0 +1,53 @@
+/**
+ * The `resolveSection` reference algorithm of `spec/v1/localized-content.md`
+ * §C, shared verbatim with conforming hosts (RFC 0103; amended by RFC 0206
+ * §B.4). One copy, so the major-1 scenario and the corpus coherence test
+ * cannot drift apart (RFC 0206 register G5).
+ *
+ * `resolveSectionRfc0103` is the algorithm exactly as RFC 0103 shipped it,
+ * FROZEN: it exists only so the RFC 0206 §B.5 identity property can be
+ * checked (the amended algorithm returns what this one returns on every
+ * section that was valid before RFC 0206). Never edit it.
+ *
+ * @see spec/v1/localized-content.md §C
+ * @see RFCS/0206-locale-keys-accept-negotiated-bcp47.md §B
+ */
+
+export type Section = {
+  data: Record<string, unknown>;
+  localizations: Record<string, Record<string, unknown>>;
+};
+
+/** RFC 0206 §A.1 — the case-canonical BCP 47 subset every stored locale key matches. */
+export const LOCALE_KEY_PATTERN = '^[a-z]{2,3}(-[A-Z][a-z]{3})?(-([A-Z]{2}|[0-9]{3}))?$';
+/** RFC 0103's subset, superseded by RFC 0206 (kept for the superset and identity properties). */
+export const LOCALE_KEY_PATTERN_RFC0103 = '^[a-z]{2}(-[A-Z]{2})?$';
+
+/** §C as amended by RFC 0206 §B.4: exact → script-family → language-family → base. */
+export function resolveSection(section: Section, negotiatedLocale: string, baseLocale: string): Record<string, unknown> {
+  const loc = section.localizations ?? {};
+  if (negotiatedLocale === baseLocale || Object.keys(loc).length === 0) return section.data;
+  if (loc[negotiatedLocale]) return { ...section.data, ...loc[negotiatedLocale] };
+  const parts = negotiatedLocale.split('-');
+  if (parts.length >= 3 && /^[A-Za-z]{4}$/.test(parts[1]!)) {
+    const ls = `${parts[0]}-${parts[1]}`;
+    if (loc[ls]) return { ...section.data, ...loc[ls] };
+  }
+  if (parts.length >= 2) {
+    const lang = parts[0]!;
+    if (loc[lang]) return { ...section.data, ...loc[lang] };
+  }
+  return section.data;
+}
+
+/** §C exactly as RFC 0103 shipped it — FROZEN (the RFC 0206 §B.5 identity oracle). */
+export function resolveSectionRfc0103(section: Section, negotiatedLocale: string, baseLocale: string): Record<string, unknown> {
+  const loc = section.localizations ?? {};
+  if (negotiatedLocale === baseLocale || Object.keys(loc).length === 0) return section.data;
+  if (loc[negotiatedLocale]) return { ...section.data, ...loc[negotiatedLocale] };
+  if (negotiatedLocale.includes('-')) {
+    const lang = negotiatedLocale.split('-')[0]!;
+    if (loc[lang]) return { ...section.data, ...loc[lang] };
+  }
+  return section.data;
+}

package/src/lib/mcp-fake-server.ts

@@ -61,6 +61,19 @@ export interface McpInvocation {
   readonly revision: string;
 }
 
+/**
+ * RFC 0204: one request the server answered, with the JSON-RPC `result` (or
+ * `error`) it sent back, byte-for-byte as serialised. `ctx.mcp` rows compare a
+ * host's resolved value to THIS — the expected value is what the suite's server
+ * actually returned, never something read from the host.
+ */
+export interface McpExchange {
+  readonly method: string;
+  readonly params: unknown;
+  readonly result?: unknown;
+  readonly error?: unknown;
+}
+
 /** MCP 2026-07-28 spec-reserved error codes (§error-codes; the -32020..-32099
  *  range is reserved for the specification). */
 export const MCP_ERR = {
@@ -96,6 +109,34 @@ const NEEDS_INPUT_LOOP_TOOL = {
   inputSchema: { type: 'object', properties: { rounds: { type: 'integer', minimum: 1 } }, required: ['rounds'] },
 };
 
+/**
+ * RFC 0204 fixture tools (2026-07-28 only). `structured-echo` returns a fixed
+ * `CallToolResult` carrying `structuredContent` and the caller's `nonce` in
+ * `_meta`, so a host that re-wraps, drops `_meta` or answers from a cache
+ * cannot reproduce it; `always-error` answers `isError: true` with a fixed
+ * `content[]` (a tool error is a result, not a rejection).
+ */
+const STRUCTURED_ECHO_TOOL = {
+  name: 'structured-echo',
+  title: 'Structured echo',
+  description: 'Returns a fixed CallToolResult: text "ok", structuredContent { n: 7, nonce }, and _meta carrying the nonce.',
+  inputSchema: { type: 'object', properties: { nonce: { type: 'string' } }, required: ['nonce'], additionalProperties: false },
+  outputSchema: { type: 'object', properties: { n: { type: 'integer' }, nonce: { type: 'string' } }, required: ['n', 'nonce'], additionalProperties: false },
+  annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+  _meta: { 'dev.openwop.conformance/fixture': 'rfc-0204' },
+};
+const ALWAYS_ERROR_TOOL = {
+  name: 'always-error',
+  description: 'Always answers a CallToolResult with isError: true and a fixed content[].',
+  inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+  annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+};
+export const ALWAYS_ERROR_CONTENT = [{ type: 'text', text: 'conformance: always-error is a tool error, reported inside the result' }] as const;
+/** RFC 0204 §D.11: the server claims read-only; a host MUST NOT believe it. */
+export const READONLY_CLAIM_PREFIX = 'conformance_readonly_claim_';
+/** Tools per `tools/list` page under 2026-07-28 (RFC 0204 §A.4: the host returns ONE page and forwards the cursor). */
+export const TOOLS_PAGE_SIZE = 3;
+
 export class McpFakeServer {
   private _server: Server | null = null;
   private _boundPort = 0;
@@ -105,6 +146,9 @@ export class McpFakeServer {
   /** RFC 0153 §D witness hook: when set, tool results carry an extension
    *  `_meta` key asserting authority the host MUST treat as opaque. */
   private _nextResultAssertsAuthority = false;
+  private readonly _exchanges: McpExchange[] = [];
+  /** Per-instance, so no host can have classified the read-only-claim tool in advance. */
+  private readonly _claimNonce = Math.random().toString(36).slice(2, 10);
 
   /**
    * @param opts.protocolVersions revisions spoken. Default `['2026-07-28',
@@ -166,7 +210,29 @@ export class McpFakeServer {
     return this._invocations;
   }
 
+  /** RFC 0204: every answered request with the result/error it was sent. */
+  exchanges(): readonly McpExchange[] {
+    return this._exchanges;
+  }
+
+  /** RFC 0204 §D.11: the name of the tool this server annotates `readOnlyHint: true` (unknowable before start). */
+  readonlyClaimToolName(): string {
+    return `${READONLY_CLAIM_PREFIX}${this._claimNonce}`;
+  }
+
+  /** The 2026-07-28 `tools/list` catalogue, in page order. */
+  currentTools(): ReadonlyArray<Record<string, unknown>> {
+    const claim = {
+      name: this.readonlyClaimToolName(),
+      description: 'Claims to be read-only. It is not classified by any host; RFC 0204 §D.11 makes it safetyTier "write".',
+      inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+      annotations: { readOnlyHint: true, destructiveHint: false },
+    };
+    return [ECHO_TOOL, STRUCTURED_ECHO_TOOL, ALWAYS_ERROR_TOOL, claim, NEEDS_INPUT_TOOL, NEEDS_INPUT_LOOP_TOOL];
+  }
+
   reset(): void {
+    this._exchanges.length = 0;
     this._invocations.length = 0;
     this._stateCounter = 0;
     this._nextResultAssertsAuthority = false;
@@ -235,11 +301,23 @@ export class McpFakeServer {
     }
 
     if (revision === CURRENT) {
-      json(...this._respondCurrent(rpc, headers));
+      const [status, payload] = this._respondCurrent(rpc, headers);
+      if (typeof rpc.method === 'string') {
+        // Recorded as the client will parse it (a JSON round trip), so a
+        // deep-equal against a host's resolved value compares like with like.
+        const wire = JSON.parse(JSON.stringify(payload)) as { result?: unknown; error?: unknown };
+        this._exchanges.push({ method: rpc.method, params: rpc.params ?? null, ...('result' in wire ? { result: wire.result } : {}), ...('error' in wire ? { error: wire.error } : {}) });
+      }
+      json(status, payload);
       return;
     }
     // legacy (2025-06-18 handshake, or an explicit legacy header)
-    json(200, this._respondLegacy(rpc));
+    const legacy = this._respondLegacy(rpc);
+    if (typeof rpc.method === 'string') {
+      const wire = JSON.parse(JSON.stringify(legacy)) as { result?: unknown; error?: unknown };
+      this._exchanges.push({ method: rpc.method, params: rpc.params ?? null, ...('result' in wire ? { result: wire.result } : {}), ...('error' in wire ? { error: wire.error } : {}) });
+    }
+    json(200, legacy);
   }
 
   // ─── MCP 2026-07-28 ────────────────────────────────────────────────────────
@@ -282,8 +360,21 @@ export class McpFakeServer {
           cacheScope: 'public',
         });
 
-      case 'tools/list':
-        return ok({ resultType: 'complete', tools: [ECHO_TOOL, NEEDS_INPUT_TOOL, NEEDS_INPUT_LOOP_TOOL], ttlMs: 60_000, cacheScope: 'public' });
+      case 'tools/list': {
+        // RFC 0204 §A.4: paged, so a host that merges pages or drops the
+        // cursor is visible. The cursor is opaque to the client; an unknown
+        // one is refused, never silently read as page 1.
+        const tools = this.currentTools();
+        const cursor = params['cursor'];
+        let start = 0;
+        if (cursor !== undefined) {
+          const m = typeof cursor === 'string' ? /^fake-page:(\d+)$/.exec(cursor) : null;
+          if (m === null || Number(m[1]) <= 0 || Number(m[1]) >= tools.length) return err(200, -32602, `Invalid cursor: ${JSON.stringify(cursor)}`);
+          start = Number(m[1]);
+        }
+        const end = Math.min(tools.length, start + TOOLS_PAGE_SIZE);
+        return ok({ resultType: 'complete', tools: tools.slice(start, end), ...(end < tools.length ? { nextCursor: `fake-page:${end}` } : {}), ttlMs: 60_000, cacheScope: 'private' });
+      }
 
       case 'tools/call': {
         const name = params['name'];
@@ -298,6 +389,16 @@ export class McpFakeServer {
           this._nextResultAssertsAuthority = false;
           return ok({ resultType: 'complete', content: [{ type: 'text', text }], isError: false, ...extra });
         }
+        if (name === 'structured-echo') {
+          const nonce = String(((params['arguments'] ?? {}) as { nonce?: unknown }).nonce ?? '');
+          return ok({ resultType: 'complete', content: [{ type: 'text', text: 'ok' }], structuredContent: { n: 7, nonce }, _meta: { 'dev.openwop.conformance/nonce': nonce } });
+        }
+        if (name === 'always-error') {
+          return ok({ resultType: 'complete', content: [...ALWAYS_ERROR_CONTENT], isError: true });
+        }
+        if (name === this.readonlyClaimToolName()) {
+          return ok({ resultType: 'complete', content: [{ type: 'text', text: 'this tool claimed to be read-only' }] });
+        }
         if (name === 'needs_input_loop') {
           // The ceiling fixture (RFC 0175 §E.1): re-issues `input_required` for
           // `arguments.rounds` retries before completing, so a host's MRTR loop

package/src/lib/node-pack-runtime.ts

@@ -0,0 +1,41 @@
+/**
+ * Reference manifest-semantics check for the `remote` runtime's MCP registry
+ * record (RFC 0203 §A.3).
+ *
+ * JSON Schema cannot compare two values in one document, so the rule "when
+ * `runtime.mcpServer` is present, `runtime.entry` MUST equal
+ * `runtime.mcpServer.remotes[0].url`" is stated in prose
+ * (`spec/v2/core/node-pack-runtimes.md` §"The MCP registry record") and
+ * enforced by a validator. This is the suite's reference form of that
+ * validator; the registry publish validator (openwop-registry) applies the
+ * same equality.
+ *
+ * Returns `null` when the manifest satisfies the rule (including every
+ * manifest that carries no `mcpServer`), or the refusal a validator emits.
+ *
+ * @see RFCS/0203-remote-runtime-mcp-registry-record.md §A.3
+ */
+
+export interface RemoteEntryRefusal {
+  readonly code: 'pack_validation_failed';
+  readonly message: string;
+}
+
+function asRecord(v: unknown): Record<string, unknown> | null {
+  return v !== null && typeof v === 'object' && !Array.isArray(v) ? (v as Record<string, unknown>) : null;
+}
+
+export function remoteEntryBinding(manifest: unknown): RemoteEntryRefusal | null {
+  const runtime = asRecord(asRecord(manifest)?.['runtime']);
+  if (runtime === null) return null;
+  const record = asRecord(runtime['mcpServer']);
+  if (record === null) return null;
+  const remotes = record['remotes'];
+  const first = Array.isArray(remotes) ? asRecord(remotes[0]) : null;
+  const url = first?.['url'];
+  if (typeof url === 'string' && runtime['entry'] === url) return null;
+  return {
+    code: 'pack_validation_failed',
+    message: `runtime.entry (${JSON.stringify(runtime['entry'])}) MUST equal runtime.mcpServer.remotes[0].url (${JSON.stringify(url)})`,
+  };
+}

package/src/lib/oauth-as-double.ts

@@ -0,0 +1,316 @@
+/**
+ * RFC 0199 — a suite-owned OAuth 2.0 authorization-server double, and a
+ * protected-resource double (RFC 9728) for the MCP-reach legs.
+ *
+ * The host under test is the OAuth CLIENT. Every leg that asserts "the host
+ * made no token request" reads THIS double's counter, which the suite owns —
+ * never the host's own ledger (a row that reads the host's ledger to prove the
+ * host did not act cannot fail).
+ *
+ *   GET  /.well-known/oauth-authorization-server   RFC 8414 metadata (switchable)
+ *   GET  /authorize                                  plays the consenting user: 302 to
+ *                                                    redirect_uri?code&state[&iss]
+ *   POST /token                                      authorization_code (PKCE-checked)
+ *                                                    and refresh_token; EVERY request counted
+ *
+ * The protected-resource double serves `/.well-known/oauth-protected-resource<path>`
+ * and answers any other request `401` with a `resource_metadata` challenge.
+ *
+ * Reachability. Each double listens on loopback (or `OPENWOP_CONFORMANCE_HARNESS_HOST`)
+ * and is advertised through `resolvePublicFront`, so an operator can front it
+ * with a public https tunnel: `OPENWOP_OAUTH_AS_URL` (+ `_PORT` to pin the
+ * listener), `OPENWOP_OAUTH_AS2_URL` (the foreign issuer a PRM may name), and
+ * `OPENWOP_OAUTH_RESOURCE_URL`. Without a front the host must relax its egress
+ * guard to reach them, which a bundle records as a relaxation.
+ */
+import { createServer, type IncomingMessage, type Server, type ServerResponse } from 'node:http';
+import { createHash, randomBytes } from 'node:crypto';
+import { receiverBinding, resolvePublicFront } from './webhook-receiver.js';
+import { driver, type OpenWOPResponse } from './driver.js';
+import { v2Discovery, familyAdvertised } from './v2.js';
+import { seamsProfileAdvertised, SEAMS_PREFIX } from './seams.js';
+
+export interface TokenRequest {
+  grantType: string;
+  params: Record<string, string>;
+  at: number;
+  status: number;
+  /** why the double refused it, when it did */
+  refused?: string;
+}
+
+export interface AuthorizeRequest { params: Record<string, string>; at: number }
+
+interface CodeRecord { clientId: string; redirectUri: string; challenge: string | null; method: string | null; resource: string | null; used: boolean; scope: string }
+
+export interface AsDouble {
+  /** The issuer identifier — the public front when set, else the local URL. No trailing slash. */
+  readonly issuer: string;
+  readonly authorizeUrl: string;
+  readonly tokenUrl: string;
+  readonly tunnelled: boolean;
+  readonly tokenRequests: TokenRequest[];
+  readonly authorizeRequests: AuthorizeRequest[];
+  readonly metadataHits: string[];
+  /** RFC 9207 — advertise authorization_response_iss_parameter_supported (default true). */
+  issParameterSupported: boolean;
+  /** RFC 8414 code_challenge_methods_supported (default ['S256']; `null` omits the member). */
+  codeChallengeMethods: string[] | null;
+  /** Overrides for the metadata document (a mismatch the host must refuse). */
+  metadataOverride: Record<string, unknown>;
+  /** When true every refresh_token grant is refused invalid_grant (a revoked refresh token). */
+  refreshRevoked: boolean;
+  /** Token requests whose grant is authorization_code. */
+  codeExchanges(): TokenRequest[];
+  close(): Promise<void>;
+}
+
+export const S256 = (verifier: string): string => createHash('sha256').update(verifier).digest('base64url');
+
+function readBody(req: IncomingMessage): Promise<string> {
+  return new Promise((ok) => {
+    const chunks: Buffer[] = [];
+    req.on('data', (c: Buffer) => chunks.push(c));
+    req.on('end', () => ok(Buffer.concat(chunks).toString('utf8')));
+  });
+}
+
+function formOf(body: string, contentType: string | undefined): Record<string, string> {
+  if (contentType !== undefined && /json/i.test(contentType)) {
+    try { return Object.fromEntries(Object.entries(JSON.parse(body) as Record<string, unknown>).map(([k, v]) => [k, String(v)])); } catch { return {}; }
+  }
+  return Object.fromEntries(new URLSearchParams(body).entries());
+}
+
+async function listen(server: Server, portEnv: string): Promise<string> {
+  const pinned = Number(process.env[portEnv] ?? '');
+  const port = Number.isInteger(pinned) && pinned > 0 && pinned < 65536 ? pinned : 0;
+  const binding = receiverBinding();
+  // A pinned port is shared by every scenario file that starts this double, and
+  // vitest runs files in parallel: wait for the holder to close rather than fail.
+  const deadline = Date.now() + 25_000;
+  for (;;) {
+    const e = await new Promise<NodeJS.ErrnoException | null>((ok) => {
+      const onErr = (err: NodeJS.ErrnoException): void => ok(err);
+      server.once('error', onErr);
+      server.listen(port, binding.bind, () => { server.off('error', onErr); ok(null); });
+    });
+    if (e === null) break;
+    if (e.code !== 'EADDRINUSE' || port === 0 || Date.now() > deadline) throw e;
+    await new Promise((ok) => setTimeout(ok, 250));
+  }
+  const addr = server.address();
+  if (typeof addr !== 'object' || addr === null) throw new Error('double address unavailable');
+  return `http://${binding.advertise}:${addr.port}`;
+}
+
+/** Start an authorization-server double. `frontEnv` names its public front (default OPENWOP_OAUTH_AS_URL). */
+export async function startAsDouble(frontEnv = 'OPENWOP_OAUTH_AS_URL'): Promise<AsDouble> {
+  const tokenRequests: TokenRequest[] = [];
+  const authorizeRequests: AuthorizeRequest[] = [];
+  const metadataHits: string[] = [];
+  const codes = new Map<string, CodeRecord>();
+  const refresh = new Set<string>();
+  let issuer = '';
+  const state = {
+    issParameterSupported: true,
+    codeChallengeMethods: ['S256'] as string[] | null,
+    metadataOverride: {} as Record<string, unknown>,
+    refreshRevoked: false,
+  };
+  const json = (res: ServerResponse, status: number, body: unknown): void => { res.writeHead(status, { 'Content-Type': 'application/json', 'Cache-Control': 'no-store' }); res.end(JSON.stringify(body)); };
+  const server = createServer((req, res) => {
+    void (async () => {
+      const url = new URL(req.url ?? '/', 'http://double');
+      if (req.method === 'GET' && url.pathname.startsWith('/.well-known/oauth-authorization-server')) {
+        metadataHits.push(url.pathname);
+        const md: Record<string, unknown> = {
+          issuer,
+          authorization_endpoint: `${issuer}/authorize`,
+          token_endpoint: `${issuer}/token`,
+          response_types_supported: ['code'],
+          grant_types_supported: ['authorization_code', 'refresh_token'],
+          authorization_response_iss_parameter_supported: state.issParameterSupported,
+          ...(state.codeChallengeMethods === null ? {} : { code_challenge_methods_supported: state.codeChallengeMethods }),
+          ...state.metadataOverride,
+        };
+        return json(res, 200, md);
+      }
+      if (req.method === 'GET' && url.pathname === '/authorize') {
+        const params = Object.fromEntries(url.searchParams.entries());
+        authorizeRequests.push({ params, at: Date.now() });
+        const redirectUri = params['redirect_uri'];
+        if (params['response_type'] !== 'code' || redirectUri === undefined) return json(res, 400, { error: 'invalid_request' });
+        const code = `code-${randomBytes(12).toString('hex')}`;
+        codes.set(code, { clientId: params['client_id'] ?? '', redirectUri, challenge: params['code_challenge'] ?? null, method: params['code_challenge_method'] ?? null, resource: params['resource'] ?? null, used: false, scope: params['scope'] ?? '' });
+        const to = new URL(redirectUri);
+        to.searchParams.set('code', code);
+        if (params['state'] !== undefined) to.searchParams.set('state', params['state']);
+        to.searchParams.set('iss', issuer);
+        res.writeHead(302, { Location: to.toString() });
+        return res.end();
+      }
+      if (req.method === 'POST' && url.pathname === '/token') {
+        const params = formOf(await readBody(req), req.headers['content-type']);
+        const grantType = params['grant_type'] ?? '';
+        const record = (status: number, refused?: string): void => { tokenRequests.push({ grantType, params, at: Date.now(), status, ...(refused ? { refused } : {}) }); };
+        if (grantType === 'authorization_code') {
+          const c = codes.get(params['code'] ?? '');
+          if (!c || c.used) { record(400, 'unknown or used code'); return json(res, 400, { error: 'invalid_grant' }); }
+          c.used = true;
+          if (params['redirect_uri'] !== c.redirectUri) { record(400, 'redirect_uri mismatch'); return json(res, 400, { error: 'invalid_grant' }); }
+          if (c.challenge !== null) {
+            const verifier = params['code_verifier'] ?? '';
+            const ok = c.method === 'S256' ? S256(verifier) === c.challenge : verifier === c.challenge;
+            if (!ok) { record(400, 'PKCE verifier does not match'); return json(res, 400, { error: 'invalid_grant' }); }
+          }
+          const rt = `rt-${randomBytes(12).toString('hex')}`;
+          refresh.add(rt);
+          record(200);
+          return json(res, 200, { access_token: `at-${randomBytes(12).toString('hex')}`, token_type: 'Bearer', expires_in: 3600, refresh_token: rt, scope: c.scope });
+        }
+        if (grantType === 'refresh_token') {
+          if (state.refreshRevoked || !refresh.has(params['refresh_token'] ?? '')) { record(400, 'refresh token revoked'); return json(res, 400, { error: 'invalid_grant' }); }
+          record(200);
+          return json(res, 200, { access_token: `at-${randomBytes(12).toString('hex')}`, token_type: 'Bearer', expires_in: 3600 });
+        }
+        record(400, 'unsupported grant');
+        return json(res, 400, { error: 'unsupported_grant_type' });
+      }
+      return json(res, 404, { error: 'not_found' });
+    })();
+  });
+  const local = await listen(server, frontEnv.replace(/_URL$/, '_PORT'));
+  const front = resolvePublicFront(frontEnv, local);
+  issuer = front.url.replace(/\/+$/, '');
+  const d: AsDouble = {
+    issuer,
+    authorizeUrl: `${issuer}/authorize`,
+    tokenUrl: `${issuer}/token`,
+    tunnelled: front.tunnelled,
+    tokenRequests,
+    authorizeRequests,
+    metadataHits,
+    get issParameterSupported() { return state.issParameterSupported; },
+    set issParameterSupported(v: boolean) { state.issParameterSupported = v; },
+    get codeChallengeMethods() { return state.codeChallengeMethods; },
+    set codeChallengeMethods(v: string[] | null) { state.codeChallengeMethods = v; },
+    get metadataOverride() { return state.metadataOverride; },
+    set metadataOverride(v: Record<string, unknown>) { state.metadataOverride = v; },
+    get refreshRevoked() { return state.refreshRevoked; },
+    set refreshRevoked(v: boolean) { state.refreshRevoked = v; },
+    codeExchanges: () => tokenRequests.filter((t) => t.grantType === 'authorization_code'),
+    close: () => new Promise<void>((ok) => server.close(() => ok())),
+  };
+  return d;
+}
+
+export interface ResourceDouble {
+  /** The protected resource's canonical URI (the MCP server URL a pack names). */
+  readonly resource: string;
+  readonly tunnelled: boolean;
+  readonly hits: string[];
+  /** The PRM document served; mutate to rewrite it (the pinning leg). */
+  prm: Record<string, unknown>;
+  close(): Promise<void>;
+}
+
+/** Start a protected-resource double at path `/mcp`, whose PRM names `authorizationServers`. */
+export async function startResourceDouble(authorizationServers: string[], frontEnv = 'OPENWOP_OAUTH_RESOURCE_URL'): Promise<ResourceDouble> {
+  const hits: string[] = [];
+  let resource = '';
+  const holder = { prm: {} as Record<string, unknown> };
+  const server = createServer((req, res) => {
+    const url = new URL(req.url ?? '/', 'http://double');
+    hits.push(`${req.method ?? ''} ${url.pathname}`);
+    if (req.method === 'GET' && url.pathname.startsWith('/.well-known/oauth-protected-resource')) {
+      res.writeHead(200, { 'Content-Type': 'application/json' });
+      return res.end(JSON.stringify(holder.prm));
+    }
+    res.writeHead(401, { 'WWW-Authenticate': `Bearer resource_metadata="${new URL(resource).origin}/.well-known/oauth-protected-resource/mcp"` });
+    return res.end();
+  });
+  const local = await listen(server, frontEnv.replace(/_URL$/, '_PORT'));
+  const front = resolvePublicFront(frontEnv, local);
+  resource = `${front.url.replace(/\/+$/, '')}/mcp`;
+  holder.prm = { resource, authorization_servers: authorizationServers, bearer_methods_supported: ['header'] };
+  return {
+    resource,
+    tunnelled: front.tunnelled,
+    hits,
+    get prm() { return holder.prm; },
+    set prm(v: Record<string, unknown>) { holder.prm = v; },
+    close: () => new Promise<void>((ok) => server.close(() => ok())),
+  };
+}
+
+/**
+ * Play the user agent through one grant: GET the authorization URL at the
+ * double (it answers 302 to the host's redirect URI with code/state/iss) and
+ * return that callback URL, unfollowed, so a leg can alter it before the host
+ * sees it.
+ */
+export async function consent(authorizationUrl: string): Promise<URL | null> {
+  const res = await fetch(authorizationUrl, { redirect: 'manual' });
+  const loc = res.headers.get('location');
+  return res.status >= 300 && res.status < 400 && loc !== null ? new URL(loc) : null;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Host-side helpers shared by the three RFC 0199 scenarios.
+// ─────────────────────────────────────────────────────────────────────────────
+
+
+export const AUTHORIZE_START = `${SEAMS_PREFIX}/sample/oauth/authorize-start`;
+export const EXPIRE_REFRESH = `${SEAMS_PREFIX}/sample/oauth/expire-refresh`;
+const MINT = `${SEAMS_PREFIX}/sample/auth/credential/mint`;
+
+export type OAuthGate = { ok: true; oauth: Record<string, unknown>; providers: Set<string> } | { ok: false; kind: 'inapplicable' | 'blocked'; reason: string };
+
+/** `oauth` advertised at major 2 with `authorization_code`, and the seams profile (the grant is driven through `authorize-start`). */
+export async function oauthGate(): Promise<OAuthGate> {
+  const doc = await v2Discovery();
+  if (!doc) return { ok: false, kind: 'blocked', reason: 'v2 discovery unreachable' };
+  const oauth = await familyAdvertised('oauth');
+  if (!oauth) return { ok: false, kind: 'inapplicable', reason: 'oauth not advertised at major 2 — the host is not an OAuth client' };
+  const grants = Array.isArray(oauth['grants']) ? (oauth['grants'] as unknown[]).map(String) : [];
+  if (!grants.includes('authorization_code')) return { ok: false, kind: 'inapplicable', reason: `oauth.grants [${grants.join(', ')}] does not list authorization_code` };
+  // An absent seams advert means the host never claimed the instrument — inapplicable, not blocked.
+  if (!seamsProfileAdvertised(doc)) return { ok: false, kind: 'inapplicable', reason: 'conformance.seamsProfile not advertised (the host claims no seams instrument) — the grant can only be driven against the suite\'s authorization-server double through the authorize-start seam' };
+  const providers = new Set((Array.isArray(oauth['providers']) ? (oauth['providers'] as Array<{ id?: unknown }>) : []).map((p) => String(p.id)));
+  return { ok: true, oauth, providers };
+}
+
+const bearerInit = (bearer: string | undefined): { authenticated?: boolean; headers?: Record<string, string> } =>
+  bearer === undefined ? {} : { authenticated: false, headers: { Authorization: `Bearer ${bearer}` } };
+
+/** POST the authorize-start seam as `bearer` (default: the suite's key). */
+export function authorizeStart(body: Record<string, unknown>, bearer?: string): Promise<OpenWOPResponse> {
+  return driver.post(AUTHORIZE_START, body, bearerInit(bearer));
+}
+
+/** The `authorizationUrl` a 201 answered, parsed; null otherwise. */
+export function authorizationUrlOf(r: OpenWOPResponse): URL | null {
+  const u = (r.json as { authorizationUrl?: unknown } | undefined)?.authorizationUrl;
+  if (r.status !== 201 || typeof u !== 'string') return null;
+  try { return new URL(u); } catch { return null; }
+}
+
+/** GET a host URL as the user agent (a callback or a connectUrl), never following a redirect. */
+export async function userAgentGet(url: string | URL, bearer: string | null): Promise<{ status: number; location: string | null; text: string }> {
+  const res = await fetch(url, { redirect: 'manual', headers: bearer === null ? { Accept: 'application/json' } : { Accept: 'application/json', Authorization: `Bearer ${bearer}` } });
+  return { status: res.status, location: res.headers.get('location'), text: await res.text() };
+}
+
+/**
+ * A second Subject: a fresh credential from the per-lane mint seam (same
+ * tenant, new subject), else OPENWOP_TEST_TENANT_B_API_KEY. null ⇒ the
+ * same-Subject legs are blocked.
+ */
+export async function secondSubject(): Promise<{ bearer: string; how: string } | null> {
+  const minted = await driver.post(MINT, { lane: 'api-key' }).catch(() => null);
+  const cred = (minted?.json as { credential?: unknown } | undefined)?.credential;
+  if (minted !== null && minted.status < 300 && typeof cred === 'string') return { bearer: cred, how: 'a fresh api-key Subject from the credential mint seam' };
+  const b = process.env['OPENWOP_TEST_TENANT_B_API_KEY'];
+  return b ? { bearer: b, how: 'OPENWOP_TEST_TENANT_B_API_KEY' } : null;
+}