@tineira/apc-conformance 0.7.1 → 0.9.0

package/dist/cli.js

@@ -3,6 +3,7 @@
  * `apc-conformance`: the HTTP conformance checks (`http.ts`) against a live app, from a terminal.
  *
  *   npx @tineira/apc-conformance@next https://pulse.example --grant https://pulse.example/mcp/<sid>/<secret>
+ *   APC_TOKEN=… npx @tineira/apc-conformance@next https://app.example --grant https://app.example/api/mcp --bearer-env APC_TOKEN
  *
  * PASS, FAIL or SKIP per check; exit 1 on any FAIL, 2 on a usage error; `--json` for the report as JSON.
  */
@@ -12,12 +13,17 @@ import { HttpConformanceUsageError, redactSecrets, runHttpConformance } from "./
 const HELP = `apc-conformance: checks a live APC app over HTTP (https://apc.tineira.com/docs)
 
 Usage:
-  apc-conformance <app-origin> [--grant <mcp-url>] [--revoked <mcp-url>] [--json] [--allow-http] [--timeout <s>]
+  apc-conformance <app-origin> [--grant <mcp-url>] [--bearer-env <VAR>] [--revoked <mcp-url>] [--revoked-bearer-env <VAR>]
+                  [--json] [--allow-http] [--timeout <s>]
 
   <app-origin>        The app's origin, e.g. https://pulse.apc.tineira.com
   --grant <mcp-url>   The MCP URL of a live agent connected directly (Direct profile). Runs the MCP checks:
                       initialize, tools/list, get_current_view, wait_for_focus, unknown grant 404.
+  --bearer-env <VAR>  The name of an environment variable that holds the grant's bearer token, for an app whose
+                      agents authenticate with OAuth (one MCP URL shared by every grant, APC 0.8). The token is
+                      sent as Authorization: Bearer and never printed. Never put a token on the command line.
   --revoked <mcp-url> The MCP URL of a grant you revoked in the app: checks the revoked answer.
+  --revoked-bearer-env <VAR>  The same, for the revoked grant's token.
   --json              Print the report as JSON.
   --allow-http        Allow http:, for a dev server on the host localhost, 127.0.0.1 or [::1] only (not *.localhost).
   --timeout <s>       Seconds per request (default 15).
@@ -65,6 +71,8 @@ async function main(argv) {
             options: {
                 grant: { type: "string" },
                 revoked: { type: "string" },
+                "bearer-env": { type: "string" },
+                "revoked-bearer-env": { type: "string" },
                 json: { type: "boolean", default: false },
                 "allow-http": { type: "boolean", default: false },
                 timeout: { type: "string" },
@@ -100,12 +108,27 @@ async function main(argv) {
         }
         timeoutMs = Math.round(s * 1000);
     }
+    // A token is read from the environment by the variable's name, never from the command line, and never printed.
+    const tokens = {};
+    for (const [flag, key] of [["bearer-env", "bearer"], ["revoked-bearer-env", "revokedBearer"]]) {
+        const name = values[flag];
+        if (name === undefined)
+            continue;
+        const token = process.env[name];
+        if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name) || !token) {
+            // The value is never echoed: a token passed here by mistake can look like a variable name.
+            process.stderr.write(`--${flag}: give the name of an environment variable that holds the token; the one given ${/^[A-Za-z_][A-Za-z0-9_]*$/.test(name) ? "is unset or empty" : "is not a variable name"} (not shown)\n`);
+            return 2;
+        }
+        tokens[key] = token;
+    }
     let report;
     try {
         report = await runHttpConformance({
             origin: positionals[0],
             ...(values.grant !== undefined ? { grant: values.grant } : {}),
             ...(values.revoked !== undefined ? { revoked: values.revoked } : {}),
+            ...tokens,
             allowHttp: values["allow-http"],
             ...(timeoutMs !== undefined ? { timeoutMs } : {}),
         });

package/dist/http.d.ts

@@ -3,8 +3,15 @@ export interface HttpConformanceOptions {
     origin: string;
     /** The MCP URL of a live grant (an agent connected directly). Without it the MCP checks are skipped. */
     grant?: string;
+    /**
+     * The grant's bearer token, when the URL alone does not carry the grant (APC 0.8: OAuth, one MCP URL shared
+     * by every grant). Sent as `Authorization: Bearer …`, never shown in the report.
+     */
+    bearer?: string;
     /** The MCP URL of a grant the person revoked in the app. Without it the revoked-answer check is skipped. */
     revoked?: string;
+    /** The revoked grant's bearer token, as `bearer` (APC 0.8). */
+    revokedBearer?: string;
     /** Lets `http:` through, on a loopback host only (localhost, 127.0.0.1, [::1]): a dev server. */
     allowHttp?: boolean;
     /** Per request, in ms (default 15000). */

package/dist/http.js

@@ -10,7 +10,7 @@
  * no credentials in URLs, every grant URL on the app's own origin, redirects never followed (a 3xx is a
  * failure), a byte cap on every body and a timeout on every request.
  */
-import { APC_JSON_MAX_BYTES, APC_JSON_PATH, APC_STANDARD_VERSION, CORE_TOOLS, REVOKED_HTTP_STATUS, declaresMcpUrl, isRevokedAnswer, parseApcManifest, } from "@tineira/apc-protocol";
+import { APC_JSON_MAX_BYTES, APC_JSON_PATH, APC_STANDARD_VERSION, CORE_TOOLS, REVOKED_HTTP_STATUS, REVOKED_HTTP_STATUS_BEARER, declaresMcpUrl, isRevokedAnswer, parseApcManifest, } from "@tineira/apc-protocol";
 import { ConformanceError, ISO, attentionOf, checkCoreToolList, checkFocusShape, checkView, data, expect, isObject, resultKey, rpcBody, standardSupport } from "./shared.js";
 /**
  * The checks of the suite that need the person's page (an adapter in process), not reachable over HTTP:
@@ -30,6 +30,8 @@ export const IN_PROCESS_ONLY = [
     { name: "apc_link: the offer, the code and its refusals, revoke and unlink of a linked agent", why: "needs Dock connections through a hub and the agent bar (link adapter)" },
 ];
 const DEFAULT_TIMEOUT_MS = 15_000;
+/** A revoked bearer grant's challenge (APC 0.8). */
+const INVALID_TOKEN = /^bearer\b.*error="?invalid_token"?/i;
 /** The most bytes read of an MCP reply. */
 const MCP_MAX_BYTES = 1_048_576;
 const PROTOCOL_VERSION = "2025-06-18";
@@ -155,6 +157,14 @@ export function httpConformance(options) {
 function build(options) {
     const { origin, grant, revoked } = checkOptions(options);
     const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    for (const [token, what] of [[options.bearer, "the bearer token"], [options.revokedBearer, "the revoked grant's bearer token"]]) {
+        if (token !== undefined && (!token || /[\s,"]/.test(token) || token.length > 8192))
+            throw new HttpConformanceUsageError(`${what} is empty or not a token (not shown)`);
+    }
+    /** The credential headers of the live grant and of the revoked one (APC 0.8): the two may share one URL, so each check says which it sends. */
+    const bearer = (token) => (token ? { authorization: `Bearer ${token}` } : {});
+    const liveAuth = bearer(options.bearer);
+    const revokedAuth = bearer(options.revokedBearer);
     const doFetch = options.fetch ?? ((request) => fetch(request));
     let manifest = null;
     let manifestRaw = undefined;
@@ -173,7 +183,7 @@ function build(options) {
             await response.body?.cancel().catch(() => { });
             throw new ConformanceError(`${init.method ?? "GET"} ${shown(url)}: answered with a redirect (HTTP ${response.status}); APC never follows one`);
         }
-        return { status: response.status, contentType: response.headers.get("content-type") ?? "", text: await readCapped(response, maxBytes, url) };
+        return { status: response.status, contentType: response.headers.get("content-type") ?? "", wwwAuthenticate: response.headers.get("www-authenticate") ?? "", text: await readCapped(response, maxBytes, url) };
     }
     async function readCapped(response, maxBytes, url) {
         const declared = Number(response.headers.get("content-length") ?? NaN);
@@ -205,18 +215,19 @@ function build(options) {
         }
         return new TextDecoder().decode(all);
     }
-    /** A grant URL is never shown whole: its secret is the grant. */
+    /** A grant URL is never shown whole: its last segment may be the secret, even when a bearer token is given too. */
     function shown(url) {
         return url === `${origin}${APC_JSON_PATH}` ? url : redactGrantUrl(url);
     }
-    async function rpc(url, method, params, abortMs) {
+    /** A JSON-RPC call; with the live grant's credential unless `headers` names another (the revoked grant's). */
+    async function rpc(url, method, params, abortMs, headers = liveAuth) {
         const started = Date.now();
         const r = await get(url.href, {
             method: "POST",
-            headers: { "content-type": "application/json", accept: "application/json, text/event-stream", "mcp-protocol-version": PROTOCOL_VERSION },
+            headers: { ...headers, "content-type": "application/json", accept: "application/json, text/event-stream", "mcp-protocol-version": PROTOCOL_VERSION },
             body: JSON.stringify({ jsonrpc: "2.0", id: 1, method, params }),
         }, MCP_MAX_BYTES, abortMs);
-        return { status: r.status, body: rpcBody(r.contentType, r.text), ms: Date.now() - started };
+        return { status: r.status, body: rpcBody(r.contentType, r.text), ms: Date.now() - started, wwwAuthenticate: r.wwwAuthenticate };
     }
     async function result(url, method, params = {}, abortMs) {
         const { status, body, ms } = await rpc(url, method, params, abortMs);
@@ -295,7 +306,9 @@ function build(options) {
             run: withGrant(async (g) => {
                 if (!manifest)
                     return "apc.json did not parse";
-                expect(declaresMcpUrl(manifest, g.href), `the grant's MCP URL ${redactGrantUrl(g.href)} is not under ${origin}${manifest.mcp.path} (mcp.path)`);
+                // With a bearer token the grants may share one URL, served at mcp.path itself (APC 0.8).
+                const shared = !!options.bearer;
+                expect(declaresMcpUrl(manifest, g.href, { shared }), `the grant's MCP URL ${shown(g.href)} is not under ${origin}${manifest.mcp.path} (mcp.path)${shared ? ", nor that path itself" : ""}`);
             }),
         },
         {
@@ -370,6 +383,8 @@ function build(options) {
             id: "grant-unknown-404",
             name: "an unknown grant answers HTTP 404, told apart from a revoked one (403)",
             run: withGrant(async (g) => {
+                if (options.bearer)
+                    return "with a bearer token the grants share the URL: an unknown token is the auth's own 401, not a URL to try";
                 const unknown = new URL(g.href);
                 const parts = unknown.pathname.split("/");
                 const last = parts.findLastIndex((p) => p.length > 0);
@@ -382,23 +397,27 @@ function build(options) {
         },
         {
             id: "revoked-answers",
-            name: `a revoked grant answers HTTP ${REVOKED_HTTP_STATUS} { error: "revoked", revoked_by, revoked_at } to every method, POST, GET and DELETE`,
+            name: `a revoked grant answers { error: "revoked", revoked_by, revoked_at } to every method, POST, GET and DELETE: HTTP ${REVOKED_HTTP_STATUS} with a secret URL, ${REVOKED_HTTP_STATUS_BEARER} with a bearer token`,
             async run() {
                 if (!revoked)
                     return "give --revoked <mcp-url>: the MCP URL of a grant you revoked in the app";
+                const bearer = !!options.revokedBearer;
+                const expected = bearer ? REVOKED_HTTP_STATUS_BEARER : REVOKED_HTTP_STATUS;
                 if (manifest)
-                    expect(declaresMcpUrl(manifest, revoked.href), `the revoked grant's MCP URL is not under ${origin}${manifest.mcp.path} (mcp.path)`);
+                    expect(declaresMcpUrl(manifest, revoked.href, { shared: bearer }), `the revoked grant's MCP URL is not under ${origin}${manifest.mcp.path} (mcp.path)`);
                 for (const [method, params] of [
                     ["initialize", { protocolVersion: PROTOCOL_VERSION, capabilities: {}, clientInfo: { name: "apc-conformance", version: APC_STANDARD_VERSION } }],
                     ["tools/list", {}],
                     ["tools/call", { name: "get_current_view", arguments: {} }],
                 ]) {
-                    const { status, body } = await rpc(revoked, method, params);
-                    expect(status === REVOKED_HTTP_STATUS, `${method} on the revoked grant: HTTP ${status}, expected ${REVOKED_HTTP_STATUS}`);
+                    const { status, body, wwwAuthenticate } = await rpc(revoked, method, params, undefined, revokedAuth);
+                    expect(status === expected, `${method} on the revoked grant: HTTP ${status}, expected ${expected}`);
+                    if (bearer)
+                        expect(INVALID_TOKEN.test(wwwAuthenticate), `${method} on the revoked grant: no WWW-Authenticate: Bearer error="invalid_token"`);
                     expect(isRevokedAnswer(body) && body.revoked_by.length > 0 && ISO.test(body.revoked_at), `${method} on the revoked grant answers ${JSON.stringify(body).slice(0, 200)}, not { error: "revoked", revoked_by, revoked_at }`);
                 }
                 for (const method of ["GET", "DELETE"]) {
-                    const r = await get(revoked.href, { method, headers: { accept: "application/json, text/event-stream", "mcp-protocol-version": PROTOCOL_VERSION } }, MCP_MAX_BYTES);
+                    const r = await get(revoked.href, { method, headers: { ...revokedAuth, accept: "application/json, text/event-stream", "mcp-protocol-version": PROTOCOL_VERSION } }, MCP_MAX_BYTES);
                     let body = null;
                     try {
                         body = JSON.parse(r.text);
@@ -406,14 +425,27 @@ function build(options) {
                     catch {
                         // not JSON
                     }
-                    expect(r.status === REVOKED_HTTP_STATUS, `${method} on the revoked grant: HTTP ${r.status}, expected ${REVOKED_HTTP_STATUS}`);
+                    expect(r.status === expected, `${method} on the revoked grant: HTTP ${r.status}, expected ${expected}`);
+                    if (bearer)
+                        expect(INVALID_TOKEN.test(r.wwwAuthenticate), `${method} on the revoked grant: no WWW-Authenticate: Bearer error="invalid_token"`);
                     expect(isRevokedAnswer(body), `${method} on the revoked grant answers ${r.text.slice(0, 200)}, not { error: "revoked", ... }`);
                 }
             },
         },
     ];
-    // Whatever a check says (a quoted body, an echoed URL, a skip reason, a note), never a grant's secret.
-    const hide = (s) => redactSecrets(s, [grant, revoked]);
+    // Whatever a check says (a quoted body, an echoed URL, a skip reason, a note), never a grant's secret or token.
+    const tokens = [options.bearer, options.revokedBearer].filter((t) => !!t);
+    const hide = (s) => {
+        let out = redactSecrets(s, [grant, revoked]);
+        // Messages cut a quoted body at 200 characters, so a token may appear cut short: any run of 8 or more of
+        // its first characters goes too, and anything sent as a Bearer credential.
+        for (const t of tokens) {
+            out = out.split(t).join("<token>");
+            if (t.length >= 8)
+                out = out.replace(new RegExp(`${escapeRegExp(t.slice(0, 8))}[^\\s"'<]*`, "g"), "<token>");
+        }
+        return out.replace(/(bearer\s+)[^\s"'<]+/gi, "$1<token>");
+    };
     const safe = checks.map((c) => ({
         ...c,
         async run() {

package/dist/hub.d.ts

@@ -0,0 +1,43 @@
+export type StandInHubMode = "ack" | "no_ack" | "redirect" | "error_500";
+export interface StandInPairing {
+    id: string;
+    agent: string;
+    mcp_url: string;
+    app_origin: string;
+    status: "pending" | "paired";
+    /** The code the app sent, raw, until it is typed right; null for an app that sent none. */
+    pairing_code: string | null;
+    attempts: number;
+}
+export interface StandInHubOptions {
+    /** The hub's origin; "https://dock.test" by default. */
+    origin?: string;
+    /** How the hub reaches the app (its `/apc/revoke` and the grant's MCP URL): in process, the app's own handler. Without it the hub calls nobody. */
+    app?: (request: Request) => Promise<Response>;
+    /** Milliseconds since the epoch, for tickets; Date.now by default. */
+    now?: () => number;
+}
+export interface StandInHub {
+    readonly origin: string;
+    /** What the app's server calls the hub with (pass it as the app's fetch, or route the hub's origin to it). */
+    readonly fetch: typeof fetch;
+    /** How the hub answers `/apc/pair`: "ack" (a hub of 0.9) unless a check sets another. */
+    mode: StandInHubMode;
+    /** A new single-use ticket for this agent, as the dock puts on a drag. */
+    ticket(agent: string): string;
+    /** The pairings it holds, pending and paired. */
+    readonly pairings: StandInPairing[];
+    /** Every `/apc/pair` body the app sent, oldest first, whatever the hub answered. */
+    readonly received: Array<Record<string, unknown>>;
+    /** The MCP URL of the agent's latest pairing. */
+    urlOf(agent: string): string | undefined;
+    /** The dock owner approves (with what they typed) or denies a pairing. */
+    decide(pairingId: string, action: "approve" | "deny", code?: unknown): Promise<{
+        ok: boolean;
+        error?: string;
+        attempts_left?: number;
+    }>;
+    /** The pairing code's time ran out: every pending pairing with a code goes, its grant given back. */
+    expire(): Promise<void>;
+}
+export declare function standInHub(options?: StandInHubOptions): StandInHub;

package/dist/hub.js

@@ -0,0 +1,147 @@
+/**
+ * A stand-in for a dock's hub (the Dock profile), for testing an app in process: what `@tineira/apc-conformance`
+ * checks a Dock app against, and what an app's own tests can pair with. It is faithful to the parts of a hub an
+ * app meets, as of APC 0.9:
+ *
+ * - **Tickets**: `ticket(agent)` mints a single-use ticket for an agent, valid `TICKET_TTL_MS`.
+ * - **`POST {hub}/apc/pair`**: checks the body before it spends the ticket (a `pairing_code` present but not a
+ *   code is `invalid_pairing_code`), keeps the code with the pending pairing and answers the acknowledgement
+ *   (`pairing_code: "required"`). An app that sends no code still pairs, as a hub in `when_sent` mode lets it.
+ * - **`POST {hub}/apc/confirm`**: whether it still pairs that agent with that MCP URL.
+ * - **The dock owner's answer** (`decide`): approving a pairing with a code needs that code; wrong ones count, and
+ *   the last of `PAIRING_CODE_MAX_ATTEMPTS` removes the pairing and gives the grant back
+ *   (`POST {app}/apc/revoke`); the right one pairs it and introduces the hub to the app (`initialize` on the
+ *   grant). `expire()` is the pairing code's time running out: every pending pairing with a code goes, its
+ *   grant given back.
+ * - **A broken hub**, for the checks that an app fails closed (`mode`): `"no_ack"` answers a yes without the
+ *   acknowledgement (a hub from before 0.9), `"redirect"` redirects `/apc/pair` to another host that says yes,
+ *   `"error_500"` says yes with HTTP 500.
+ *
+ * It never shows a code: `received` keeps what the app sent, for the checks to compare with what the app showed.
+ */
+import { normalizePairingCode, PAIRING_CODE_ACK, PAIRING_CODE_MAX_ATTEMPTS, pairingCodesMatch, TICKET_TTL_MS } from "@tineira/apc-protocol";
+const randomHex = (bytes) => [...crypto.getRandomValues(new Uint8Array(bytes))].map((b) => b.toString(16).padStart(2, "0")).join("");
+export function standInHub(options = {}) {
+    const origin = options.origin ?? "https://dock.test";
+    const now = options.now ?? Date.now;
+    const did = randomHex(16);
+    const tickets = new Map();
+    const pairings = [];
+    const received = [];
+    const json = (body, status = 200) => Response.json(body, { status });
+    const callApp = async (url, body) => {
+        if (!options.app)
+            return;
+        const response = await options.app(new Request(url, { method: "POST", headers: { "content-type": "application/json", accept: "application/json, text/event-stream" }, body: JSON.stringify(body) }));
+        await response.body?.cancel().catch(() => { });
+    };
+    const giveBack = async (p) => {
+        pairings.splice(pairings.indexOf(p), 1);
+        await callApp(`${p.app_origin}/apc/revoke`, { mcp_url: p.mcp_url });
+    };
+    const live = (ticket, agent) => {
+        const t = typeof ticket === "string" ? tickets.get(ticket) : undefined;
+        return !!t && t.agent === agent && t.expires_at > now();
+    };
+    const pair = (b) => {
+        if (typeof b.ticket !== "string" || typeof b.agent !== "string" || typeof b.mcp_url !== "string")
+            return json({ ok: false, error: "invalid" }, 400);
+        const app = b.app;
+        if (typeof app?.name !== "string" || !app.name || typeof app.origin !== "string")
+            return json({ ok: false, error: "app_not_allowed" }, 400);
+        // The body first: a malformed code leaves the ticket good.
+        const code = b.pairing_code === undefined ? null : normalizePairingCode(b.pairing_code);
+        if (b.pairing_code !== undefined && !code)
+            return json({ ok: false, error: "invalid_pairing_code" }, 400);
+        if (!live(b.ticket, b.agent))
+            return json({ ok: false, error: "ticket_expired" }, 400);
+        tickets.delete(b.ticket);
+        const p = { id: `pr_${randomHex(6)}`, agent: b.agent, mcp_url: b.mcp_url, app_origin: app.origin, status: "pending", pairing_code: code, attempts: 0 };
+        pairings.push(p);
+        return json({ ok: true, pairing_id: p.id, status: "pending", agent: { name: "Agent via dock", icon: null }, ...(code ? { pairing_code: PAIRING_CODE_ACK } : {}) });
+    };
+    const hub = {
+        origin,
+        mode: "ack",
+        pairings,
+        received,
+        ticket(agent) {
+            const ticket = `${did}.${randomHex(16)}`;
+            tickets.set(ticket, { agent, expires_at: now() + TICKET_TTL_MS });
+            return ticket;
+        },
+        urlOf: (agent) => pairings.filter((p) => p.agent === agent).at(-1)?.mcp_url,
+        fetch: (async (input, init) => {
+            const request = input instanceof Request ? input : new Request(input, init);
+            const url = new URL(request.url);
+            if (url.origin !== origin || request.method !== "POST")
+                return json({ ok: false, error: "not_found" }, 404);
+            const body = ((await request.json().catch(() => null)) ?? {});
+            if (url.pathname === "/apc/pair") {
+                received.push(body);
+                if (hub.mode === "redirect") {
+                    // A fetch that refuses redirects (as an app's must) fails; one that follows lands on another host that says yes.
+                    if ((init?.redirect ?? request.redirect) === "error")
+                        throw new TypeError(`redirect from ${request.url} refused`);
+                    const elsewhere = json({ ok: true, pairing_id: "pr_elsewhere", status: "pending", agent: { name: "Agent via dock", icon: null }, pairing_code: PAIRING_CODE_ACK });
+                    Object.defineProperty(elsewhere, "redirected", { value: true });
+                    return elsewhere;
+                }
+                if (hub.mode === "error_500")
+                    return json({ ok: true, pairing_id: "pr_500", status: "pending", agent: { name: "Agent via dock", icon: null }, pairing_code: PAIRING_CODE_ACK }, 500);
+                const answer = pair(body);
+                if (hub.mode === "no_ack" && answer.ok) {
+                    const rest = (await answer.json());
+                    delete rest.pairing_code;
+                    return json(rest);
+                }
+                return answer;
+            }
+            if (url.pathname === "/apc/confirm") {
+                if (!live(body.ticket, body.agent))
+                    return json({ ok: false, error: "ticket_expired" }, 400);
+                const p = pairings.find((x) => x.agent === body.agent && x.mcp_url === body.mcp_url);
+                if (!p)
+                    return json({ ok: false, error: "not_paired" }, 400);
+                tickets.delete(body.ticket);
+                return json({ ok: true, status: p.status, agent: { name: "Agent via dock", icon: null } });
+            }
+            return json({ ok: false, error: "not_found" }, 404);
+        }),
+        async decide(pairingId, action, code) {
+            const p = pairings.find((x) => x.id === pairingId);
+            if (!p)
+                return { ok: false, error: "unknown_pairing" };
+            if (action === "deny") {
+                await giveBack(p);
+                return { ok: true };
+            }
+            if (p.status !== "pending")
+                return { ok: false, error: "invalid_action" };
+            if (p.pairing_code) {
+                if (code === undefined || code === null || code === "")
+                    return { ok: false, error: "pairing_code_required" };
+                const given = normalizePairingCode(code);
+                if (!given)
+                    return { ok: false, error: "invalid_pairing_code" };
+                if (!pairingCodesMatch(p.pairing_code, given)) {
+                    p.attempts++;
+                    if (p.attempts < PAIRING_CODE_MAX_ATTEMPTS)
+                        return { ok: false, error: "wrong_pairing_code", attempts_left: PAIRING_CODE_MAX_ATTEMPTS - p.attempts };
+                    await giveBack(p);
+                    return { ok: false, error: "pairing_code_refused" };
+                }
+                p.pairing_code = null;
+            }
+            p.status = "paired";
+            // The hub introduces itself to the app, as a real one does on approval.
+            await callApp(p.mcp_url, { jsonrpc: "2.0", id: 1, method: "initialize", params: { protocolVersion: "2025-06-18", capabilities: {}, clientInfo: { name: "apc-hub", title: "Agent via dock", version: "0.9.0" } } });
+            return { ok: true };
+        },
+        async expire() {
+            for (const p of pairings.filter((x) => x.status === "pending" && x.pairing_code))
+                await giveBack(p);
+        },
+    };
+    return hub;
+}

package/dist/index.d.ts

@@ -8,7 +8,11 @@
  * (`GET {origin}/.well-known/apc.json`, through the adapter's `fetch`): its shape, its origin, the
  * standard, and that its profiles and `mcp.path` match what the app serves. Since 0.6 an adapter may
  * also give `page.mobile` (the page on a phone): the suite then checks that every agent is shown in the
- * page, that the bar cannot be collapsed, and that a finger can pin and unpin with no mouse drag.
+ * page, that the bar cannot be collapsed, and that a finger can pin and unpin with no mouse drag. Since 0.9
+ * an app on the Dock profile gives `dock` too: the suite pairs it with a stand-in hub (`standInHub`) and checks
+ * the pairing code (the consent shows one, new each time, and sends that one to the hub; the app keeps no grant
+ * when the hub does not acknowledge the code; wrong codes and the code's time running out give the grant back;
+ * the right code pairs).
  *
  * Framework-free: `apcConformance(app)` returns named checks that throw `ConformanceError`, for any
  * test runner (`for (const c of apcConformance(app)) test(c.name, c.run)` under `node --test`), and
@@ -19,12 +23,20 @@
  * and a revoked grant's answer); the `apc-conformance` command (`cli.ts`) runs them from a terminal.
  */
 import { type ApcProfile, type FocusTarget, type PresenceEvent } from "@tineira/apc-protocol";
+import type { StandInHub } from "./hub.js";
 export { ConformanceError } from "./shared.js";
+export { standInHub, type StandInHub, type StandInHubMode, type StandInHubOptions, type StandInPairing } from "./hub.js";
 export { HttpConformanceUsageError, IN_PROCESS_ONLY, httpConformance, redactGrantUrl, redactSecrets, runHttpConformance, type HttpCheck, type HttpCheckResult, type HttpConformanceOptions, type HttpConformanceReport, } from "./http.js";
-/** One agent's way into the app: the MCP URL its holder calls (the agent itself, or a dock's hub) and the app's id for the grant. */
+/**
+ * One agent's way into the app: the MCP URL its holder calls (the agent itself, or a dock's hub), the
+ * app's id for the grant, and (APC 0.8) the headers that carry the grant when the URL alone does not: an
+ * app whose grants share one MCP URL gives `{ authorization: "Bearer …" }`. With a secret URL, leave
+ * `headers` out.
+ */
 export interface AgentConnection {
     mcpUrl: string;
     grantId: string;
+    headers?: Record<string, string>;
 }
 /**
  * What the `apc_link` checks need (APC 0.4), from an app that offers both profiles. The suite makes the
@@ -63,6 +75,26 @@ export interface ApcMobilePage {
     /** The person removes the agent's pin with a finger (the × beside the agent in the bar). False when the page offers no way. */
     unpinByTouch(grantId: string): Promise<boolean>;
 }
+/**
+ * The Dock profile's pairing (APC 0.9), from an app on that profile: required of one that claims 0.9.0 or later.
+ * The app pairs with `hub`, a stand-in from this package (`standInHub({ app })`, whose `app` routes to the app's
+ * handler), which the app's server reaches as its hub.
+ */
+export interface ApcDockAdapter {
+    hub: StandInHub;
+    /**
+     * The person drops an agent the app holds no grant for, with a ticket from `hub.ticket(agent)`: the pairing code
+     * the app's consent shows, as the person sees it (formatted or not), and their Allow on that consent, with what
+     * the app answered the page.
+     */
+    drop(agent: string, ticket: string): Promise<{
+        shown: string;
+        allow(): Promise<{
+            ok: boolean;
+            error?: string;
+        }>;
+    }>;
+}
 /** What the suite needs from an app. */
 export interface ApcAppAdapter {
     /** The app's name, for the report. */
@@ -96,6 +128,8 @@ export interface ApcAppAdapter {
     };
     /** An app that offers both profiles: the `apc_link` checks run too. */
     link?: ApcLinkAdapter;
+    /** The Dock profile's pairing code (APC 0.9): required with `profile: "dock"` of an app that claims 0.9.0 or later. */
+    dock?: ApcDockAdapter;
 }
 export interface ConformanceCheck {
     name: string;

package/dist/index.js

@@ -8,7 +8,11 @@
  * (`GET {origin}/.well-known/apc.json`, through the adapter's `fetch`): its shape, its origin, the
  * standard, and that its profiles and `mcp.path` match what the app serves. Since 0.6 an adapter may
  * also give `page.mobile` (the page on a phone): the suite then checks that every agent is shown in the
- * page, that the bar cannot be collapsed, and that a finger can pin and unpin with no mouse drag.
+ * page, that the bar cannot be collapsed, and that a finger can pin and unpin with no mouse drag. Since 0.9
+ * an app on the Dock profile gives `dock` too: the suite pairs it with a stand-in hub (`standInHub`) and checks
+ * the pairing code (the consent shows one, new each time, and sends that one to the hub; the app keeps no grant
+ * when the hub does not acknowledge the code; wrong codes and the code's time running out give the grant back;
+ * the right code pairs).
  *
  * Framework-free: `apcConformance(app)` returns named checks that throw `ConformanceError`, for any
  * test runner (`for (const c of apcConformance(app)) test(c.name, c.run)` under `node --test`), and
@@ -18,10 +22,13 @@
  * of the suite that HTTP reaches (apc.json, and with a grant's MCP URL the core tools' shapes and timing,
  * and a revoked grant's answer); the `apc-conformance` command (`cli.ts`) runs them from a terminal.
  */
-import { APC_AGENT_CLIENT_META, APC_JSON_MAX_BYTES, APC_JSON_PATH, APC_MOBILE_VIEWPORT, APC_STANDARD_VERSION, APC_LINK_KEY, APC_LINK_TOOL, APC_LINK_TTL_S, CORE_TOOLS, LINK_REFUSED_ERROR, REVOKED_ERROR, REVOKED_HTTP_STATUS, canonicalTarget, compareStandard, declaresMcpUrl, isRevokedAnswer, parseApcManifest, } from "@tineira/apc-protocol";
+import { APC_AGENT_CLIENT_META, APC_JSON_MAX_BYTES, APC_JSON_PATH, APC_MOBILE_VIEWPORT, APC_STANDARD_VERSION, APC_LINK_KEY, APC_LINK_TOOL, APC_LINK_TTL_S, CORE_TOOLS, LINK_REFUSED_ERROR, REVOKED_ERROR, REVOKED_HTTP_STATUS, REVOKED_HTTP_STATUS_BEARER, WAIT_CLAIM_GAP_S, canonicalTarget, compareStandard, declaresMcpUrl, isRevokedAnswer, normalizePairingCode, PAIRING_CODE_MAX_ATTEMPTS, parseApcManifest, } from "@tineira/apc-protocol";
 import { ConformanceError, ISO, attentionOf, checkCoreToolList, checkFocusShape, checkView, data, expect, isObject, resultKey, rpcBody, standardSupport, text } from "./shared.js";
 export { ConformanceError } from "./shared.js";
+export { standInHub } from "./hub.js";
 export { HttpConformanceUsageError, IN_PROCESS_ONLY, httpConformance, redactGrantUrl, redactSecrets, runHttpConformance, } from "./http.js";
+/** A grant's credential travels in a header (a bearer token), not in its URL: several grants may share the URL (APC 0.8). */
+const sharesUrl = (conn) => !!conn.headers && Object.keys(conn.headers).some((h) => h.toLowerCase() === "authorization");
 /** A check whose body may resolve to `{ note }`: the note lands on the check, and `run()` stays a test body. */
 function noted(name, body) {
     const check = {
@@ -36,27 +43,53 @@ function noted(name, body) {
 }
 const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 /** One JSON-RPC request over Streamable HTTP, stateless, as a dock's hub sends it: the HTTP status and the reply. */
-async function send(app, url, method, params) {
-    const request = new Request(url, {
+async function send(app, to, method, params, signal) {
+    const request = new Request(to.mcpUrl, {
         method: "POST",
-        headers: { "content-type": "application/json", accept: "application/json, text/event-stream", "mcp-protocol-version": "2025-06-18" },
+        headers: { ...to.headers, "content-type": "application/json", accept: "application/json, text/event-stream", "mcp-protocol-version": "2025-06-18" },
         body: JSON.stringify({ jsonrpc: "2.0", id: 1, method, params }),
+        ...(signal ? { signal } : {}),
     });
     const response = await (app.fetch ? app.fetch(request) : fetch(request));
     const body = rpcBody(response.headers.get("content-type") ?? "", await response.text());
-    return { status: response.status, body };
+    return { status: response.status, body, headers: response.headers };
 }
-async function result(app, url, method, params = {}) {
-    const { status, body } = await send(app, url, method, params);
+/** A JSON-RPC notification (no id) in a POST of its own: the HTTP status (202 for a Streamable HTTP server). */
+async function notify(app, to, method, params) {
+    const request = new Request(to.mcpUrl, {
+        method: "POST",
+        headers: { ...to.headers, "content-type": "application/json", accept: "application/json, text/event-stream", "mcp-protocol-version": "2025-06-18" },
+        body: JSON.stringify({ jsonrpc: "2.0", method, params }),
+    });
+    const response = await (app.fetch ? app.fetch(request) : fetch(request));
+    await response.body?.cancel().catch(() => { });
+    return response.status;
+}
+/** What a check of a 0.8 rule says of an app that claims an earlier standard: passed, not checked. */
+const NOT_08 = { note: "not checked: the app's apc.json claims a standard before 0.8.0, which does not have this rule" };
+async function result(app, to, method, params = {}, signal) {
+    const { status, body } = await send(app, to, method, params, signal);
     expect(status === 200, `${method}: HTTP ${status}, expected 200 (${JSON.stringify(body).slice(0, 200)})`);
     expect(isObject(body) && !("error" in body && body.error), `${method}: JSON-RPC error ${JSON.stringify(body).slice(0, 200)}`);
     return body.result;
 }
-async function call(app, url, tool, args = {}) {
-    const r = await result(app, url, "tools/call", { name: tool, arguments: args });
+async function call(app, to, tool, args = {}, signal) {
+    const r = await result(app, to, "tools/call", { name: tool, arguments: args }, signal);
     expect(isObject(r), `${tool}: no result`);
     return r;
 }
+/**
+ * A revoked grant's answer (APC 0.8): a `RevokedAnswer` body, with the binding's status: 403 for a secret URL, 401 with
+ * `WWW-Authenticate: Bearer error="invalid_token"` for a bearer token.
+ */
+function checkRevoked(conn, status, body, what, headers) {
+    const bearer = sharesUrl(conn);
+    const expected = bearer ? REVOKED_HTTP_STATUS_BEARER : REVOKED_HTTP_STATUS;
+    expect(status === expected, `${what} on a revoked grant: HTTP ${status}, expected ${expected}`);
+    if (bearer)
+        expect(/^bearer\b.*error="?invalid_token"?/i.test(headers.get("www-authenticate") ?? ""), `${what} on a revoked bearer grant: no WWW-Authenticate: Bearer error="invalid_token"`);
+    expect(isRevokedAnswer(body) && body.revoked_by.length > 0 && ISO.test(body.revoked_at), `${what} on a revoked grant answers { error: "revoked", revoked_by, revoked_at }: ${JSON.stringify(body).slice(0, 200)}`);
+}
 /** A focus in the core's format, naming `target`. */
 function checkFocus(focus, target, where) {
     const parsed = checkFocusShape(focus, where);
@@ -72,10 +105,17 @@ async function timed(work) {
 export function apcConformance(app) {
     const [first, second] = app.targets;
     const check = (name, run) => noted(`${app.name} (${app.profile}): ${name}`, run);
+    /** Whether the app's apc.json claims `version` or later: a rule added in a version is checked only of apps that claim it. */
+    const claims = async (conn, version) => {
+        const request = new Request(`${new URL(conn.mcpUrl).origin}${APC_JSON_PATH}`, { headers: { accept: "application/json" } });
+        const response = await (app.fetch ? app.fetch(request) : fetch(request));
+        const standard = (await response.json().catch(() => ({}))).standard;
+        return typeof standard === "string" && compareStandard(standard, version) >= 0;
+    };
     return [
         check("serves apc.json from its own origin, naming the profiles it serves and where its MCP URLs live", async () => {
-            const { mcpUrl } = await app.connect();
-            const origin = new URL(mcpUrl).origin;
+            const conn = await app.connect();
+            const origin = new URL(conn.mcpUrl).origin;
             const request = new Request(`${origin}${APC_JSON_PATH}`, { headers: { accept: "application/json" } });
             const response = await (app.fetch ? app.fetch(request) : fetch(request));
             expect(response.status === 200, `GET ${APC_JSON_PATH}: HTTP ${response.status}, expected 200`);
@@ -98,21 +138,23 @@ export function apcConformance(app) {
             expect(m.profiles.includes(app.profile), `profiles ${JSON.stringify(m.profiles)} leave out ${app.profile}, which the app serves`);
             if (app.link)
                 expect(m.profiles.includes("direct") && m.profiles.includes("dock"), `profiles ${JSON.stringify(m.profiles)}: an app that links both paths offers both`);
-            expect(declaresMcpUrl(m, mcpUrl), `the grant's MCP URL is not under ${origin}${m.mcp.path} (mcp.path)`);
+            // A Direct app whose grants share one URL (a bearer token names the grant) may serve it at mcp.path itself (APC 0.8).
+            const shared = app.profile === "direct" && sharesUrl(conn);
+            expect(declaresMcpUrl(m, conn.mcpUrl, { shared }), `the grant's MCP URL is not under ${origin}${m.mcp.path} (mcp.path)${shared ? ", nor that path itself" : ""}`);
             if (m.profiles.includes("direct"))
                 expect(m.direct && new URL(m.direct.connect).origin === origin, "direct.connect is the app's own page");
             if (support.note)
                 return { note: support.note };
         }),
         check("lists the core tools, with their arguments", async () => {
-            const { mcpUrl } = await app.connect();
-            checkCoreToolList(await result(app, mcpUrl, "tools/list"), CORE_TOOLS);
+            const conn = await app.connect();
+            checkCoreToolList(await result(app, conn, "tools/list"), CORE_TOOLS);
         }),
         check("get_current_view returns the view as identifiers, and no focus before a pin", async () => {
-            const { mcpUrl } = await app.connect();
+            const conn = await app.connect();
             await app.page.setOpen(true);
             await app.page.showView();
-            const r = await call(app, mcpUrl, "get_current_view");
+            const r = await call(app, conn, "get_current_view");
             expect(!r.isError, "get_current_view failed");
             const d = data(r);
             expect("view" in d && "focus" in d, "the result has view and focus");
@@ -121,29 +163,31 @@ export function apcConformance(app) {
             expect(attentionOf(r) === undefined, "no pin, so no attention");
         }),
         check("a pin rides as attention on any result until it is read, and next reads it", async () => {
-            const { mcpUrl, grantId } = await app.connect();
+            const conn = await app.connect();
+            const { grantId } = conn;
             expect(await app.page.pin(grantId, first), "the app refused a pin on the first target");
-            const probed = await call(app, mcpUrl, app.probe.tool, app.probe.args);
+            const probed = await call(app, conn, app.probe.tool, app.probe.args);
             expect(!probed.isError, `${app.probe.tool} failed`);
             const attention = attentionOf(probed);
             expect(isObject(attention) && typeof attention.note === "string", "an unread pin puts attention { focus, note } on the result");
             checkFocus(attention.focus, first, "attention");
-            const view = await call(app, mcpUrl, "get_current_view");
+            const view = await call(app, conn, "get_current_view");
             const focus = checkFocus(data(view).focus, first, "get_current_view");
-            const after = await call(app, mcpUrl, app.probe.tool, app.probe.args);
+            const after = await call(app, conn, app.probe.tool, app.probe.args);
             expect(attentionOf(after) === undefined, "reading the focus marks it seen: no attention after");
-            const read = await call(app, mcpUrl, focus.next, focus.next_args);
+            const read = await call(app, conn, focus.next, focus.next_args);
             expect(!read.isError, `next (${String(focus.next)}) with next_args failed: ${JSON.stringify(read.content).slice(0, 200)}`);
             // One pin per grant: a new drop replaces it, unread again.
             expect(await app.page.pin(grantId, second), "the app refused a pin on the second target");
-            const again = attentionOf(await call(app, mcpUrl, app.probe.tool, app.probe.args));
+            const again = attentionOf(await call(app, conn, app.probe.tool, app.probe.args));
             expect(isObject(again), "a new pin is unread again");
             checkFocus(again.focus, second, "attention after a second pin");
         }),
         check("wait_for_focus returns a pin dropped during the wait", async () => {
-            const { mcpUrl, grantId } = await app.connect();
+            const conn = await app.connect();
+            const { grantId } = conn;
             await app.page.setOpen(true);
-            const waiting = timed(call(app, mcpUrl, "wait_for_focus", { timeout_s: 10 }));
+            const waiting = timed(call(app, conn, "wait_for_focus", { timeout_s: 10 }));
             await sleep(300);
             expect(await app.page.pin(grantId, second), "the app refused the pin");
             const { value: r, ms } = await waiting;
@@ -152,13 +196,13 @@ export function apcConformance(app) {
             expect(d.timed_out === false, "a wait that got a pin did not time out");
             checkFocus(d.focus, second, "wait_for_focus");
             expect(ms < 9000, `it returned at ${ms} ms, not soon after the pin`);
-            const after = await call(app, mcpUrl, app.probe.tool, app.probe.args);
+            const after = await call(app, conn, app.probe.tool, app.probe.args);
             expect(attentionOf(after) === undefined, "the wait marks the pin seen");
         }),
         check("wait_for_focus times out cleanly", async () => {
-            const { mcpUrl } = await app.connect();
+            const conn = await app.connect();
             await app.page.setOpen(true);
-            const { value: r, ms } = await timed(call(app, mcpUrl, "wait_for_focus", { timeout_s: 1 }));
+            const { value: r, ms } = await timed(call(app, conn, "wait_for_focus", { timeout_s: 1 }));
             expect(!r.isError, "wait_for_focus failed");
             const d = data(r);
             expect(d.focus === null && d.timed_out === true, `a wait with no pin times out: ${JSON.stringify(d)}`);
@@ -168,9 +212,9 @@ export function apcConformance(app) {
             expect(text(r).then === undefined && d.then === undefined, "a wait that came back empty ends the loop: no then");
         }),
         check("wait_for_focus ends when the person has no page open", async () => {
-            const { mcpUrl } = await app.connect();
+            const conn = await app.connect();
             await app.page.setOpen(false);
-            const { value: r, ms } = await timed(call(app, mcpUrl, "wait_for_focus", { timeout_s: 3 }));
+            const { value: r, ms } = await timed(call(app, conn, "wait_for_focus", { timeout_s: 3 }));
             const d = data(r);
             expect(d.focus === null, "no pin, no focus");
             if (d.page_open === undefined)
@@ -181,25 +225,33 @@ export function apcConformance(app) {
             }
             await app.page.setOpen(true);
         }),
-        check("then rides on results only while the person's page is open", async () => {
-            const { mcpUrl } = await app.connect();
+        check("then rides on results only while the person's page is open and the agent was pinned lately", async () => {
+            const conn = await app.connect();
             await app.page.setOpen(true);
-            const open = await call(app, mcpUrl, app.probe.tool, app.probe.args);
+            const v08 = await claims(conn, "0.8.0");
+            if (v08) {
+                const unpinned = await call(app, conn, app.probe.tool, app.probe.args);
+                expect(resultKey(unpinned, "then").value === undefined && text(unpinned).then === undefined, "an open page with no pin gives no then (APC 0.8): the agent does not wait after every answer");
+            }
+            expect(await app.page.pin(conn.grantId, first), "the app refused the pin");
+            expect(!(await call(app, conn, "get_current_view")).isError, "get_current_view failed");
+            const open = await call(app, conn, app.probe.tool, app.probe.args);
             // resultKey: the same value in the structured result and the text (a text-only model follows the text).
             const then = resultKey(open, "then");
             expect(typeof then.value === "string" && typeof text(open).then === "string", "with the page open, a result carries then, structured and in the text");
             await app.page.setOpen(false);
-            const closed = await call(app, mcpUrl, app.probe.tool, app.probe.args);
+            const closed = await call(app, conn, app.probe.tool, app.probe.args);
             expect(resultKey(closed, "then").value === undefined && text(closed).then === undefined, "with no page open, no then");
             await app.page.setOpen(true);
         }),
         check("presence names what a read touched, with ids only", async () => {
-            const { mcpUrl, grantId } = await app.connect();
+            const conn = await app.connect();
+            const { grantId } = conn;
             await app.page.setOpen(true);
             expect(await app.page.pin(grantId, first), "the app refused the pin");
-            const focus = checkFocus(data(await call(app, mcpUrl, "get_current_view")).focus, first, "get_current_view");
+            const focus = checkFocus(data(await call(app, conn, "get_current_view")).focus, first, "get_current_view");
             app.page.takePresence();
-            const read = await call(app, mcpUrl, focus.next, focus.next_args);
+            const read = await call(app, conn, focus.next, focus.next_args);
             expect(!read.isError, "next failed");
             const events = app.page.takePresence().filter((e) => e.grant_id === grantId && e.tool === focus.next);
             expect(events.length === 1, `one presence event for the read, got ${events.length}`);
@@ -218,13 +270,12 @@ export function apcConformance(app) {
             expect(await app.page.pin(a.grantId, first), "the app refused the pin");
             expect(await app.page.revoke(a.grantId), "the app refused to revoke");
             for (const [method, params] of [["initialize", { protocolVersion: "2025-06-18", capabilities: {}, clientInfo: { name: "apc-conformance", version: "0" } }], ["tools/list", {}], ["tools/call", { name: "get_current_view", arguments: {} }], ["tools/call", { name: app.probe.tool, arguments: app.probe.args }]]) {
-                const { status, body } = await send(app, a.mcpUrl, method, params);
-                expect(status === REVOKED_HTTP_STATUS, `${method} on a revoked grant: HTTP ${status}, expected ${REVOKED_HTTP_STATUS}`);
-                expect(isRevokedAnswer(body) && body.revoked_by.length > 0 && ISO.test(body.revoked_at), `${method} on a revoked grant answers { error: "revoked", revoked_by, revoked_at }: ${JSON.stringify(body).slice(0, 200)}`);
+                const { status, body, headers } = await send(app, a, method, params);
+                checkRevoked(a, status, body, method, headers);
             }
             // Whatever the HTTP method: a GET (the SSE stream) or a DELETE (ending a session) is answered "revoked" too, not 405.
             for (const method of ["GET", "DELETE"]) {
-                const request = new Request(a.mcpUrl, { method, headers: { accept: "application/json, text/event-stream", "mcp-protocol-version": "2025-06-18" } });
+                const request = new Request(a.mcpUrl, { method, headers: { ...a.headers, accept: "application/json, text/event-stream", "mcp-protocol-version": "2025-06-18" } });
                 const response = await (app.fetch ? app.fetch(request) : fetch(request));
                 const text = await response.text();
                 let body = null;
@@ -234,17 +285,17 @@ export function apcConformance(app) {
                 catch {
                     // not JSON
                 }
-                expect(response.status === REVOKED_HTTP_STATUS, `${method} on a revoked grant: HTTP ${response.status}, expected ${REVOKED_HTTP_STATUS}`);
-                expect(isRevokedAnswer(body), `${method} on a revoked grant answers { error: "revoked", revoked_by, revoked_at }: ${text.slice(0, 200)}`);
+                checkRevoked(a, response.status, body, method, response.headers);
             }
             expect(!(await app.page.pin(a.grantId, second)), "a revoked agent cannot be pinned");
-            const other = await call(app, b.mcpUrl, "get_current_view");
+            const other = await call(app, b, "get_current_view");
             expect(!other.isError && "view" in data(other), "another agent is not touched");
         }),
         check("a call already running when the grant is revoked ends revoked, with no data", async () => {
-            const { mcpUrl, grantId } = await app.connect();
+            const conn = await app.connect();
+            const { grantId } = conn;
             await app.page.setOpen(true);
-            const waiting = timed(call(app, mcpUrl, "wait_for_focus", { timeout_s: 10 }));
+            const waiting = timed(call(app, conn, "wait_for_focus", { timeout_s: 10 }));
             await sleep(300);
             expect(await app.page.revoke(grantId), "the app refused to revoke");
             const { value: r, ms } = await waiting;
@@ -254,10 +305,183 @@ export function apcConformance(app) {
             expect(!("focus" in d) && !("view" in d) && r.structuredContent === undefined, "it carries no focus, view or other data");
             expect(ms < 9000, `it ended at ${ms} ms, not soon after the revoke`);
         }),
+        check("one wait per grant: a newer wait takes over, and the older one delivers nothing (APC 0.8)", async () => {
+            const conn = await app.connect();
+            if (!(await claims(conn, "0.8.0")))
+                return NOT_08;
+            await app.page.setOpen(true);
+            const older = call(app, conn, "wait_for_focus", { timeout_s: 10 });
+            await sleep((WAIT_CLAIM_GAP_S + 0.3) * 1000);
+            const newer = timed(call(app, conn, "wait_for_focus", { timeout_s: 10 }));
+            const old = data(await older);
+            expect(old.focus === null && old.timed_out === false && typeof old.note === "string", `the wait a newer one took over ends with focus null, timed_out false and a note: ${JSON.stringify(old).slice(0, 200)}`);
+            expect(await app.page.pin(conn.grantId, first), "the app refused the pin");
+            const { value: got, ms } = await newer;
+            checkFocus(data(got).focus, first, "the newer wait");
+            expect(ms < 9000, `the newer wait returned at ${ms} ms, not soon after the pin`);
+        }),
+        check("a second wait started right after the first is refused with retry_after_s, and the first still delivers (APC 0.8)", async () => {
+            const conn = await app.connect();
+            if (!(await claims(conn, "0.8.0")))
+                return NOT_08;
+            await app.page.setOpen(true);
+            const running = call(app, conn, "wait_for_focus", { timeout_s: 10 });
+            await sleep(200);
+            const refused = data(await call(app, conn, "wait_for_focus", { timeout_s: 10 }));
+            expect(refused.focus === null && refused.timed_out === false, `the second wait is refused: ${JSON.stringify(refused).slice(0, 200)}`);
+            expect(typeof refused.retry_after_s === "number" && refused.retry_after_s >= 1 && refused.retry_after_s <= WAIT_CLAIM_GAP_S + 1, `with retry_after_s, 1 to ${WAIT_CLAIM_GAP_S + 1}: ${JSON.stringify(refused).slice(0, 200)}`);
+            expect(typeof refused.note === "string" && refused.note.length > 0, "and a note");
+            expect(await app.page.pin(conn.grantId, second), "the app refused the pin");
+            checkFocus(data(await running).focus, second, "the first wait, still running");
+        }),
+        ...["notifications/cancelled", "an HTTP abort"].map((how) => check(`a pin is never lost to a cancelled wait (${how}): it marks nothing seen and frees its place at once (APC 0.8)`, async () => {
+            const conn = await app.connect();
+            if (!(await claims(conn, "0.8.0")))
+                return NOT_08;
+            await app.page.setOpen(true);
+            const controller = new AbortController();
+            // Not awaited before the pin: a handler that ignores the cancel would still be waiting, and would take the pin.
+            const waiting = call(app, conn, "wait_for_focus", { timeout_s: 10 }, how === "an HTTP abort" ? controller.signal : undefined).catch(() => null);
+            await sleep(300);
+            if (how === "an HTTP abort")
+                controller.abort();
+            // MCP's cancel, in a POST of its own, as a client of a stateless server sends it.
+            else
+                expect((await notify(app, conn, "notifications/cancelled", { requestId: 1, reason: "apc-conformance" })) < 300, "notifications/cancelled was not accepted");
+            await sleep(300);
+            expect(await app.page.pin(conn.grantId, first), "the app refused the pin");
+            // Past a poll of a wait that ignored the cancel (2 s in @tineira/apc-server), so it would have taken the pin by now.
+            await sleep(2500);
+            const attention = attentionOf(await call(app, conn, app.probe.tool, app.probe.args));
+            expect(isObject(attention), `the pin dropped after the cancelled wait is still unread: it rides as attention (the cancelled wait took it)`);
+            checkFocus(attention.focus, first, "attention after a cancelled wait");
+            const again = data(await call(app, conn, "wait_for_focus", { timeout_s: 2 }));
+            expect(again.retry_after_s === undefined, `a cancelled wait frees its place at once: ${JSON.stringify(again).slice(0, 200)}`);
+            checkFocus(again.focus, first, "the next wait gets the pin");
+            await Promise.race([waiting, sleep(11_000)]);
+        })),
         ...mobileChecks(app, app.page.mobile),
+        ...(app.profile === "dock" ? dockChecks(app, app.dock) : []),
         ...(app.link ? linkChecks(app, app.link) : []),
     ];
 }
+/** What a check of a 0.9 rule says of an app that claims an earlier standard: passed, not checked. */
+const NOT_09 = { note: "not checked: the app's apc.json claims a standard before 0.9.0, which does not have the pairing code" };
+/** The standard an app's apc.json claims, read from the origin of one of its grants. */
+async function claimedStandard(app, conn) {
+    const request = new Request(`${new URL(conn.mcpUrl).origin}${APC_JSON_PATH}`, { headers: { accept: "application/json" } });
+    const response = await (app.fetch ? app.fetch(request) : fetch(request));
+    return (await response.json().catch(() => ({}))).standard;
+}
+/**
+ * The pairing code (APC 0.9), on the Dock profile: the consent shows a well-formed code, new for every consent,
+ * and the app sends that code to the hub; the app keeps no grant unless the hub acknowledges the code with a
+ * plain 200; five wrong codes, or the code's time running out, give the grant back; the right code pairs.
+ */
+function dockChecks(app, dock) {
+    const check = (name, run) => noted(`${app.name} (dock): pairing code: ${name}`, run);
+    let n = 0;
+    /** A new agent's drop, Allowed: what the consent showed, the app's answer, and the pairing the hub got. */
+    const allowNew = async (d) => {
+        const agent = `ag_code_${++n}_${Date.now().toString(36)}`;
+        const drop = await d.drop(agent, d.hub.ticket(agent));
+        const answer = await drop.allow();
+        return { agent, shown: drop.shown, answer, sent: d.hub.received.at(-1), pairing: d.hub.pairings.find((p) => p.agent === agent) };
+    };
+    /** The HTTP status the app gives a grant's MCP URL: 404 once it holds no grant there. */
+    const statusOf = async (mcpUrl) => (await send(app, { mcpUrl, grantId: "" }, "initialize", { protocolVersion: "2025-06-18", capabilities: {}, clientInfo: { name: "apc-conformance", version: "1" } })).status;
+    /** Whether the app claims 0.9.0 or later, read through a grant made the usual way. */
+    const claims09 = async () => {
+        const claimed = await claimedStandard(app, await app.connect());
+        return typeof claimed === "string" && compareStandard(claimed, "0.9.0") >= 0;
+    };
+    return [
+        check("the dock adapter is given (required of an app that claims 0.9.0 or later on the Dock profile)", async () => {
+            if (dock)
+                return;
+            const claimed = await claimedStandard(app, await app.connect());
+            expect(typeof claimed === "string" && compareStandard(claimed, "0.9.0") < 0, `apc.json claims standard ${String(claimed)}, which requires the pairing code to be checked: give dock in the adapter (ApcDockAdapter: hub, drop)`);
+        }),
+        check("the consent shows a well-formed code, and the app sends that code, raw, to the hub", async () => {
+            if (!dock)
+                return;
+            if (!(await claims09()))
+                return NOT_09;
+            const { shown, answer, sent } = await allowNew(dock);
+            const code = normalizePairingCode(shown);
+            expect(code, `the consent shows ${JSON.stringify(shown)}, not a pairing code (6 characters of Crockford base32)`);
+            expect(answer.ok, `the Allow did not pair: ${answer.error}`);
+            expect(isObject(sent), "the app sent the hub no /apc/pair");
+            expect(sent.pairing_code !== undefined, "the app sent /apc/pair without pairing_code: an app of 0.9 must send the code its consent showed");
+            expect(normalizePairingCode(sent.pairing_code) === sent.pairing_code, `the app sent pairing_code ${JSON.stringify(sent.pairing_code)}: send it raw, 6 characters, no dash`);
+            expect(sent.pairing_code === code, "the app sent the hub another code than the one its consent showed");
+        }),
+        check("every consent shows a new code", async () => {
+            if (!dock)
+                return;
+            if (!(await claims09()))
+                return NOT_09;
+            const a = `ag_two_${++n}`;
+            const b = `ag_two_${++n}`;
+            const first = normalizePairingCode((await dock.drop(a, dock.hub.ticket(a))).shown);
+            const second = normalizePairingCode((await dock.drop(b, dock.hub.ticket(b))).shown);
+            expect(first && second, "a consent shows no pairing code");
+            expect(first !== second, `two consents showed the same code, ${first}`);
+        }),
+        check("a hub that does not acknowledge the code, redirects, or says yes with HTTP 500 holds no grant", async () => {
+            if (!dock)
+                return;
+            if (!(await claims09()))
+                return NOT_09;
+            try {
+                for (const mode of ["no_ack", "redirect", "error_500"]) {
+                    dock.hub.mode = mode;
+                    const { answer, sent } = await allowNew(dock);
+                    expect(!answer.ok, `with a hub that answers ${mode}, the Allow says it paired: the app must refuse it`);
+                    expect(isObject(sent) && typeof sent.mcp_url === "string", `with a hub that answers ${mode}, the app sent no MCP URL to check`);
+                    const status = await statusOf(sent.mcp_url);
+                    expect(status === 404, `with a hub that answers ${mode}, the grant the app made still answers (HTTP ${status}): it must be deleted before the app answers its page`);
+                }
+            }
+            finally {
+                dock.hub.mode = "ack";
+            }
+        }),
+        check(`${PAIRING_CODE_MAX_ATTEMPTS} wrong codes, or the code's time running out, give the grant back`, async () => {
+            if (!dock)
+                return;
+            if (!(await claims09()))
+                return NOT_09;
+            const wrong = await allowNew(dock);
+            expect(wrong.answer.ok && wrong.pairing, `the Allow did not pair: ${wrong.answer.error}`);
+            const code = normalizePairingCode(wrong.shown);
+            const other = code.startsWith("A") ? "BBBBBB" : "AAAAAA";
+            for (let i = 1; i <= PAIRING_CODE_MAX_ATTEMPTS; i++)
+                await dock.hub.decide(wrong.pairing.id, "approve", other);
+            expect(!dock.hub.pairings.includes(wrong.pairing), "the stand-in hub kept a pairing after the last wrong code");
+            const afterWrong = await statusOf(wrong.pairing.mcp_url);
+            expect(afterWrong === 404, `after ${PAIRING_CODE_MAX_ATTEMPTS} wrong codes the hub gave the grant back, and it still answers (HTTP ${afterWrong})`);
+            const late = await allowNew(dock);
+            expect(late.answer.ok && late.pairing, `the Allow did not pair: ${late.answer.error}`);
+            await dock.hub.expire();
+            const afterExpiry = await statusOf(late.pairing.mcp_url);
+            expect(afterExpiry === 404, `the code's time ran out and the hub gave the grant back, and it still answers (HTTP ${afterExpiry})`);
+        }),
+        check("the right code pairs, and the grant answers", async () => {
+            if (!dock)
+                return;
+            if (!(await claims09()))
+                return NOT_09;
+            const { shown, answer, pairing } = await allowNew(dock);
+            expect(answer.ok && pairing, `the Allow did not pair: ${answer.error}`);
+            const decided = await dock.hub.decide(pairing.id, "approve", shown);
+            expect(decided.ok, `the code the consent showed did not approve the pairing: ${decided.error}`);
+            const conn = { mcpUrl: pairing.mcp_url, grantId: "" };
+            const listed = await send(app, conn, "tools/list", {});
+            expect(listed.status === 200, `the paired grant answers tools/list with HTTP ${listed.status}`);
+        }),
+    ];
+}
 /** The mobile rule (APC 0.6): on a phone the agents are in the page, never collapsed, and a finger can pin and unpin. */
 function mobileChecks(app, mobile) {
     const [first, second] = app.targets;
@@ -267,8 +491,8 @@ function mobileChecks(app, mobile) {
         check("the page adapter for a phone is given (required of an app that claims 0.6.0 or later)", async () => {
             if (mobile)
                 return;
-            const { mcpUrl } = await app.connect();
-            const request = new Request(`${new URL(mcpUrl).origin}${APC_JSON_PATH}`, { headers: { accept: "application/json" } });
+            const conn = await app.connect();
+            const request = new Request(`${new URL(conn.mcpUrl).origin}${APC_JSON_PATH}`, { headers: { accept: "application/json" } });
             const response = await (app.fetch ? app.fetch(request) : fetch(request));
             const claimed = (await response.json().catch(() => ({}))).standard;
             expect(typeof claimed === "string" && compareStandard(claimed, "0.6.0") < 0, `apc.json claims standard ${String(claimed)}, which requires the mobile rule to be checked: give page.mobile in the adapter (ApcMobilePage: agentBar, pinByTouch, unpinByTouch)`);
@@ -287,18 +511,19 @@ function mobileChecks(app, mobile) {
         check("a person pins with a finger, no mouse drag, and the agent reads the pin; unpin works by touch too", async () => {
             if (!mobile)
                 return;
-            const { mcpUrl, grantId } = await app.connect();
+            const conn = await app.connect();
+            const { grantId } = conn;
             await app.page.setOpen(true);
             await app.page.showView();
             expect(await mobile.pinByTouch(grantId, first), "the page refused a pin made by tapping the agent and then the target");
-            const r = await call(app, mcpUrl, "get_current_view");
+            const r = await call(app, conn, "get_current_view");
             expect(!r.isError, "get_current_view failed");
             checkFocus(data(r).focus, first, "get_current_view after a pin by touch");
             // The same again on another target: one pin per grant, replaced.
             expect(await mobile.pinByTouch(grantId, second), "the page refused a second pin by touch");
-            checkFocus(data(await call(app, mcpUrl, "get_current_view")).focus, second, "get_current_view after a second pin by touch");
+            checkFocus(data(await call(app, conn, "get_current_view")).focus, second, "get_current_view after a second pin by touch");
             expect(await mobile.unpinByTouch(grantId), "the page offers no way to remove the pin with a finger");
-            const after = await call(app, mcpUrl, "get_current_view");
+            const after = await call(app, conn, "get_current_view");
             expect(data(after).focus === null, "the pin is still there after the person removed it by touch");
         }),
     ];
@@ -308,7 +533,7 @@ async function arrive(app, conn, client) {
     const params = conn.path === "direct"
         ? { protocolVersion: "2025-06-18", capabilities: {}, clientInfo: { name: client, version: "1.0.0" } }
         : { protocolVersion: "2025-06-18", capabilities: {}, clientInfo: { name: "apc-hub", title: `${client} via dock`, version: "0.1.0" }, _meta: { [APC_AGENT_CLIENT_META]: client } };
-    await result(app, conn.mcpUrl, "initialize", params);
+    await result(app, conn, "initialize", params);
 }
 /** The offer on a result, where the model sees it: in the structured result and the same in the text. */
 function offerOf(r) {
@@ -335,13 +560,13 @@ function linkChecks(app, link) {
         await arrive(app, direct, name);
         const dock = await connect("dock");
         await arrive(app, dock, name);
-        const offered = await call(app, dock.mcpUrl, app.probe.tool, app.probe.args);
+        const offered = await call(app, dock, app.probe.tool, app.probe.args);
         expect(!offered.isError, `${app.probe.tool} failed`);
         const offer = offerOf(offered);
         expect(offer, `the second connection of ${name}, on the other path, gets apc_link on a result of one of the app's own tools`);
         return { name, direct, dock, offer };
     };
-    const redeem = (conn, code) => call(app, conn.mcpUrl, APC_LINK_TOOL, { code });
+    const redeem = (conn, code) => call(app, conn, APC_LINK_TOOL, { code });
     const refused = (r, reason, where) => {
         expect(r.isError === true, `${where}: refused, as a tool error (${JSON.stringify(r).slice(0, 200)})`);
         const d = text(r);
@@ -349,13 +574,13 @@ function linkChecks(app, link) {
     };
     const linkedEntry = async (a, b) => (await link.agents()).find((e) => e.grants.includes(a) && e.grants.includes(b));
     const works = async (conn, where) => {
-        const r = await call(app, conn.mcpUrl, "get_current_view");
+        const r = await call(app, conn, "get_current_view");
         expect(!r.isError && "view" in data(r), `${where} still reads the app`);
     };
     return [
         check("the same client on the other path is offered a code once per session, and the code links them", async () => {
             const { direct, dock, offer } = await pair();
-            const again = await call(app, dock.mcpUrl, app.probe.tool, app.probe.args);
+            const again = await call(app, dock, app.probe.tool, app.probe.args);
             expect(offerOf(again) === undefined, "asked at most once per MCP session");
             const done = await redeem(direct, offer.code);
             expect(!done.isError && data(done).linked === true, `the other connection redeems it: ${JSON.stringify(done).slice(0, 200)}`);
@@ -387,22 +612,22 @@ function linkChecks(app, link) {
                 await sleep((APC_LINK_TTL_S + 1) * 1000);
             refused(await redeem(direct, offer.code), "expired", "after expires_in");
             expect(!(await linkedEntry(direct.grantId, dock.grantId)), "it stays two agents");
-            expect(offerOf(await call(app, dock.mcpUrl, app.probe.tool, app.probe.args)) === undefined, "not asked again in that session");
+            expect(offerOf(await call(app, dock, app.probe.tool, app.probe.args)) === undefined, "not asked again in that session");
         }),
         check("a connection of another client is offered nothing", async () => {
             const direct = await connect("direct");
             await arrive(app, direct, client());
             const dock = await connect("dock");
             await arrive(app, dock, client());
-            expect(offerOf(await call(app, dock.mcpUrl, app.probe.tool, app.probe.args)) === undefined, "no offer between two clients");
+            expect(offerOf(await call(app, dock, app.probe.tool, app.probe.args)) === undefined, "no offer between two clients");
         }),
         check("revoke on a linked agent cuts both grants", async () => {
             const { direct, dock, offer } = await pair();
             expect(!(await redeem(direct, offer.code)).isError, "linked");
             expect(await app.page.revoke(dock.grantId), "the app refused to revoke");
             for (const [conn, where] of [[direct, "Direct"], [dock, "Dock"]]) {
-                const { status, body } = await send(app, conn.mcpUrl, "tools/call", { name: "get_current_view", arguments: {} });
-                expect(status === REVOKED_HTTP_STATUS && isRevokedAnswer(body), `the ${where} grant answers 403 revoked: HTTP ${status}`);
+                const { status, body, headers } = await send(app, conn, "tools/call", { name: "get_current_view", arguments: {} });
+                checkRevoked(conn, status, body, `get_current_view on the ${where} grant`, headers);
             }
         }),
         check("unlink shows two agents again, each with its own grant", async () => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tineira/apc-conformance",
-  "version": "0.7.1",
+  "version": "0.9.0",
   "description": "Agent Pointed Context (APC) conformance: checks an app against the standard, in process with an adapter, or live over HTTP with the apc-conformance command.",
   "keywords": [
     "apc",
@@ -45,7 +45,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@tineira/apc-protocol": "^0.7.1"
+    "@tineira/apc-protocol": "^0.9.0"
   },
   "scripts": {},
   "types": "./dist/index.d.ts",