# The Dock protocol > How an agent reaches the apps a person uses through one connection, a hub. It depends on Agent Pointed Context (APC, https://apc.tineira.com/docs/spec). The document is below in full; it is also at https://dock.tineira.com/spec.md (Markdown) and https://dock.tineira.com/ (HTML). ## Optional - [APC specification](https://apc.tineira.com/docs/spec) - [APC docs for agents](https://apc.tineira.com/llms.txt) --- # The Dock protocol **Dock 1.0 draft, published as 1.0.0-next.** `@tineira/dock-protocol` carries `DOCK_STANDARD_VERSION` `"1.0.0-next.0"`. The value `"1.0.0"` of `dock_standard` is cut together with APC 2.0, not before 2027-02-18; until then this document is a draft, and its clauses bind as part of APC 1.x. ## What this is The Dock protocol is how an agent reaches the apps a person uses through one connection, a hub. The person drags the agent from their dock onto an app they paired; after consent in the app and a pairing code, the app hands the hub a grant, and the hub relays between the agent and the app. [Agent Pointed Context (APC)](https://apc.tineira.com/docs/spec) is the standard for pointing an agent at what a person is looking at. This is its other half, about connecting, which grew inside APC and is leaving it. **Dock depends on APC, and never the reverse.** This document uses APC's terms (app, agent, grant, hub, dock, profile), APC's core (the view, the pin and the focus format, `get_current_view`, `wait_for_focus`, revoke from the app) and APC's `apc.json`, and cites them at https://apc.tineira.com/docs/spec. APC refers to nothing in this document. **APC 1.x still carries every clause below.** APC 1.1 and 1.2 marked them deprecated, unchanged and still binding, for APC 2.0 to remove; this document publishes them in their own right first. Until APC 2.0 they bind as part of APC 1.x, and an app or a hub that conforms to APC 1.x already conforms to Dock 1.0. Nothing here changes what any party does. **The text is APC's, word for word.** Each block below is copied from APC's specification at APC 1.3.0 (agent-pointed-context commit `527c3d5`) and names the section of APC it comes from. Where a sentence had to change to be true in a separate document, the change is listed in [changes from APC's text](#changes-from-apcs-text), and so is every line of APC of which a block copies only part; nothing else is reworded. APC's own notices of deprecation are its record of the marking and are not copied. The labels stay as APC numbered them: M1 to M13, H1 to H10, `CODE-2`, `DROP-1`, `TM-1` and `PAIR-2`. **How to read the copied text.** A version number in it (0.9, 0.12, 1.0, 1.x) is a version of APC, where the clause was written; this protocol's own versions are written Dock 1.0. A link to a section this document does not have opens that section of APC's specification. **MUST**, **MUST NOT**, **SHOULD**, **SHOULD NOT** and **MAY** mean what APC's specification says they mean, and each binds the party its sentence names. The sections [who Dock 1.0 binds](#who-dock-10-binds), [new in Dock 1.0](#new-in-dock-10), [changes from APC's text](#changes-from-apcs-text), the [changelog](#changelog) and the [licence](#licence) are written for this document and are not APC's text. ## Who Dock 1.0 binds Dock 1.0 binds every hub: an origin whose `apc.json` lists `"hub"`, or that holds any Dock pairing. It binds every app that implements the Dock profile **or holds any Dock grant that has not ended or been revoked**, whether or not its `apc.json` lists `"dock"` at that moment (M8 has an app stop listing it while it cannot pair, and a hub may read a copy up to 60 seconds old). Such an app **MUST** meet the app's duties of this document, M1 to M13 and every other sentence that names an app, M12 on its grants that are not Dock grants included, for as long as it implements the Dock profile or holds such a grant. An app that does not implement the Dock profile and holds no Dock grant owes nothing here. A dock's page is bound by the sentences that name it. ## The Dock profile *From [the Dock profile](https://apc.tineira.com/docs/spec#the-dock-profile) in APC's specification: the section entire but for its notice of deprecation and for the hub's tools, which stay in APC, non-normative.* The agent connects once, to a hub. The person drags it from the dock onto any app they paired. ### The drop The dock puts the agent on a drag with the type `application/x-apc-agent` and the payload `{ v: 1, agent, hub, ticket }`: a public handle, the hub's bare origin, and a ticket. The dock **MUST NOT** put a secret or an MCP URL in the payload: any page the agent is dropped on can read it. The **ticket** is single use, lives 240 seconds (since 0.9; 60 before), is bound to that agent, and opens a connect request or a confirmation and nothing else; it cannot pair. The reference dock refreshes a ticket once it has less than 180 seconds left (it checks every 10), so a drag carries one with about three minutes left, and the app's two-minute consent fits in it. ### Origin-bound first pairing: `POST {hub}/apc/connect` Since 0.13, a first drop requests a connection, before app consent. The app sends `{ticket, agent, app:{origin}}` server to server, with the same M1 to M4 guards as `/apc/pair` (`requestConnect`). The origin is a bare HTTPS origin (loopback HTTP only in development). Success is HTTP 200 `{ok:true, status:"connect_requested"}`; a refusal is HTTP 400 `{ok:false, error}`. A drop ticket cannot start `/apc/pair` (H9). The hub checks, in order: body and origin; a live drop ticket bound to the agent and an existing agent, without spending it; limits; the origin verdict (blocklist, verified origins, kill switch); the app's `apc.json`, which must offer `dock` and a same-origin fragment-free `dock_connect`; then, in one synchronous step, rechecks the ticket, spends it and inserts the request. A failure before that step leaves the drop ticket usable. A connect ticket used here is `ticket_not_for_pairing` and is not spent. The reference hub holds a request for `CONNECT_REQUEST_TTL_MS` (120 seconds), replaces one for the same (agent, app origin), allows at most three origins per agent, twenty requests per dock, and three app attempts per drop ticket (each reads `apc.json`, failed or in flight; `too_many_requests`). The owner may also create one by `POST /api/d/:did/connects {agent,host}` (a bare host or HTTPS URL, normalized by `new URL`, ports only in development). It answers `{ok:true,request}`. Connect and Deny are owner-authenticated, same-origin POSTs to `/api/d/:did/connects/:cr/approve` and `/deny`. An approve checks the agent and the current verdict again, without an outbound fetch, and only then consumes the request, in the same synchronous step. A refusal the owner can answer (`warning_required`, a refused verdict) leaves the request pending; a second approve after a successful one is `not_found`. For an unverified origin, the owner acknowledges the warning at Connect with `{action:"approve_unverified"}`. The request's acknowledgement passes through the connect ticket to the pending pairing; the code step does not warn again. The domain's `unverified_ok` is committed only on the code's approval. Deny of a connect request changes no earlier domain approval. The approve answers `{ok:true,url}`: the app's `dock_connect`, built with `new URL` and setting `hash` to `#apc_connect=` followed by base64url JSON `{v:1,hub,agent,ticket}`. A connect ticket has at least 128 random bits, lasts `TICKET_TTL_MS` (240 seconds), is single use, and is bound to the requested origin and agent. It is never a drop ticket; the reference hub keeps the same `${did}.${hex32}` format and distinguishes the tables. The dock opens the URL with `window.open(url,"_blank","noopener")`. On popup refusal it offers an explicit link with `target="_blank" rel="noopener"`. **Reader reference behaviour.** An allowed extension calls `/apc/connect {ticket,agent,reader:true,label?}`. It gets `{ok:true,status:"connect_requested",claim,check}`: a private 128-bit claim `${did}.${hex32}` and a four-digit check shown by both the extension and the dock. The reader origin is checked before the ticket; manifest lookup and the app-origin verdict are skipped. Up to three pending requests per (agent, extension origin) coexist; a request never replaces another. `/apc/reader/status {claim}` answers `{ok:true,status:"pending"}` while that claim waits. Connect deletes the request and every earlier reader and pointer for this agent and extension, cleans superseded claims, creates the paired reader, and answers `{ok:true}` with no URL or connect ticket. Status then answers `{ok:true,status:"paired",token,agent}` once, to that extension origin and claim holder; later it is `denied`. The old `/apc/reader` is a hard-cut HTTP 400 `ticket_not_for_pairing` stub, spending nothing. Removing an agent, rotating its secrets, resetting, expiry and the alarm purge connect requests and tickets. ### Consent in the app Consent is the app's server's to check, never its page's alone. The page sends every dock drop to its server; a first drop calls `/apc/connect` and says to confirm in the dock. Consent begins on `dock_connect`, in the person's own app session, after Connect in the dock. For an agent it holds no grant for (never paired, revoked, or one the dock no longer confirms), the server answers `consent_required` with a nonce; the page shows its consent with that nonce, and the Allow sends it back. The consent **SHOULD** name the hub's host from the drop (the one the app will call), the host the person has to check before the Allow; its other words are the app's own ([the UX guide](https://apc.tineira.com/docs/ux#pairing-and-consent-cards) gives an example). The server **MUST** make a grant only for a request that brings back the nonce of a consent it gave for that dock and that agent, and **MUST** accept each nonce only once. In the reference apps (`DockConsent` in `@tineira/apc-server`) the nonce has 128 random bits, works once, for the same dock and agent, for two minutes. One drop of an agent is answered at a time: a second request while the first waits on the hub answers `pairing_in_progress` (see [one pending pairing](#one-pending-pairing)). Since 0.9 the consent shows a [pairing code](#the-pairing-code), and the server answers `consent_required` with both: `{ consent, pairing_code }`. The reference apps hold the code on the page and show it only after the Allow, in the handoff card that takes the consent's place ([the UX guide](https://apc.tineira.com/docs/ux#the-handoff-card)). That is how the reference apps do it, not a rule: the rules are in the next section. ### The pairing code A drag can be put on any page, and anyone who runs a dock can make tickets for their own agent. Without a code, someone could lure an app's owner into dropping their agent and clicking Allow, and approve the pairing in their own dock. The code closes that: only the app's owner sees it, and the dock's Allow needs it. - The app **MUST** make a new code with every consent: 6 characters of Crockford base32 (`0123456789ABCDEFGHJKMNPQRSTVWXYZ`, 30 bits; `newPairingCode` in `@tineira/apc-server`), shown only on the app owner's page. After the Allow it sends the code, raw (`K7M4P2`), in `pairing_code` of `/apc/pair`, and nowhere else: not over MCP, not in a URL, not to `/apc/confirm`. - The hub keeps it with the pending pairing and **MUST NOT** show it: not in the dock's state, not in what it sends the dock's pages, not in any answer. The dock owner types it to approve; the hub compares it in constant time with what the app sent, ignoring case, spaces and dashes (O reads as 0, I and L as 1). A missing or malformed code is refused and not counted. A wrong one counts (`wrong_pairing_code`, with `attempts_left`); the fifth removes the request and gives the grant back (`pairing_code_refused`). A request with a code that nobody approves goes after two minutes, its grant given back. A match clears the code. Deny and unpair need no code. - The app **MUST** keep the grant only when the hub acknowledges the code (below), and delete it, before it answers its page, on any other answer: a hub that does not check codes never holds a grant. - The reference hub requires the code: it refuses a pairing without one (`pairing_code_required`). Other hubs **SHOULD** require it too. - Where an app shows the code it **SHOULD** tell the person to type it only in their own dock and never give it to anyone, and to Cancel if their dock does not ask for it: the code's resistance to phishing lives in the person having read that. The reference apps keep the code on the page, with a Cancel (the app's revoke), until the hub connects (its first `initialize` on the grant) or the grant goes; the card's wording is in [the UX guide](https://apc.tineira.com/docs/ux#the-handoff-card). ### Pairing: `POST {hub}/apc/pair` With the person's yes, the app's server makes a grant and hands it to the hub, server to server: ```json POST https://apc.tineira.com/apc/pair { "ticket": "…", "agent": "ag_…", "app": { "name": "Orders", "origin": "https://orders.example" }, "mcp_url": "https://orders.example/mcp/…", "pairing_code": "K7M4P2" } ``` The ticket here is the origin-bound connect ticket from the owner-approved URL, never the drop ticket. The hub refuses a drop ticket as `ticket_not_for_pairing`, and a connect ticket for another origin or agent as `ticket_origin_mismatch`, without spending either. The hub checks the body before it spends the matching connect ticket: a `pairing_code` that is present but not a code (`null`, `""`, a number) is `invalid_pairing_code`, so a malformed request leaves the ticket good. Then it checks the ticket, the app's origin and its [`apc.json`](https://apc.tineira.com/docs/spec#apcjson) (it **MUST** refuse the pairing when the file is missing, redirected, invalid, names another origin, does not list `"dock"`, or does not cover `mcp_url`), and answers HTTP 200 with `{ ok: true, pairing_id, status: "pending", agent: { name, icon }, pairing_code: "required" }`, or HTTP 400 with `{ ok: false, error }`. `pairing_code: "required"` is the acknowledgement: the hub keeps the code and will ask for it. The pairing counts only when the person has also said yes in the dock, with the code. The app links the grant to the agent only once the hub took it, and pins it. Since 0.12 the acknowledgement also carries `binding: "pairing_id"`: the hub names this pairing on every `initialize` it sends to the grant ([the binding](#the-binding)). An app accepts only that value: an acknowledgement with any other `binding`, or with `binding: "pairing_id"` and a `pairing_id` that is not 22 to 64 of `A–Z a–z 0–9 _ -`, is a refusal, and the app deletes the grant before it answers its page. An acknowledgement without `binding` is a hub before 0.12. The app **MUST** treat any other answer as a refusal and delete the grant: a redirect (never followed: [M2](#the-app-and-the-hub-call)), any status but 200 and 400, a 200 without the acknowledgement (`hub_ignores_pairing_code`), no answer within its time limit. `pairWithHub` in `@tineira/apc-server` does exactly that. Since 0.10 the call also follows [the app's rules on the hub call](#the-app-and-the-hub-call) (M1 to M9), and the grant is [in flight](#the-grants-states) until the acknowledgement. Only an absent `pairing_code` is a pairing without a code, from an app before 0.9: the reference hub refuses it with `pairing_code_required`, and other hubs **SHOULD**. ### Every drop: `POST {hub}/apc/confirm` On a drop of an agent it already holds a grant for, the app asks the hub whether that pairing still stands: `{ ticket, agent, mcp_url }`. HTTP 200 with `{ ok: true, status }` (`"pending"` or `"paired"`) pins it; while it is pending the reference apps show the pairing code again. The answer never carries the code. `{ ok: false, error: "not_paired" }` means the dock no longer pairs it: the app drops the grant and asks the person again (the ticket is still good). A hub never confirms a revoked or blocked pairing. Since 0.10 the hub expires overdue requests before it answers (H2) and answers `not_paired` for a pairing it holds as ended; what the app does with a grant still in handoff is in [one pending pairing](#one-pending-pairing). An app **MUST** ignore fields it does not know in a hub's answer to `/apc/connect`, `/apc/pair` or `/apc/confirm`: a later version may add some, and none of them changes what the app stored for a grant (since 0.12, its [binding](#the-binding) is written only from the acknowledgement of its own `/apc/pair`). ### The hub gives a grant back: `POST {app}/apc/revoke` When the person unpairs an app in the dock, denies its request, types the fifth wrong code, lets the request expire, or drops the agent again before approving (H3), the hub sends `{ mcp_url }` to the app's `/apc/revoke`, and the app ends that grant and deletes its pin. This is the hub's side; the app's own Revoke is core and needs no hub. The reference hub tries a give-back the app did not take again, a few times over half a day, and gives every grant back before a dock's data is deleted. Since 0.10 (M7) `/apc/revoke` is public and **MUST** answer the same HTTP 200 to any input, with its body capped. It ends a grant whose secret hash matches and that is in any state but revoked or ended, in flight included; that grant then answers 404. On a revoked or already ended grant it does nothing: revoked stays revoked. ### The grant's states Since 0.10 a dock grant has a state in the app, and the state says what the grant answers (`DockGrantState` and `dockGrantAnswer` in `@tineira/apc-protocol`). The states, in order of precedence, are **revoked > ended > in flight > handoff > dormant > live**: the first that applies is the one used. | State | Begins | Ends | |---|---|---| | **in flight** | the Allow | the hub's acknowledgement of `/apc/pair`; on a failure the grant ends before the page hears back. A grant still in flight `T_ack` after the Allow **MUST** end, whatever happened to the call | | **handoff** | the acknowledgement | the first `initialize` whose connection is committed | | **live** | the committed `initialize` | dormancy, revoke or end | | **dormant** (SHOULD) | `T_idle` after the last wake action (live grants only) | the next wake action | | **ended** | `T_connect` after the acknowledgement with no committed `initialize` (**MUST**); a give-back (`/apc/revoke`); long dormancy | never | | **revoked** | the owner's Revoke, or Cancel | never | The time limits (`T_ACK_MAX_MS`, `T_CONNECT_MAX_MS` and the recommended times in `@tineira/apc-protocol`): - `T_ack` **MUST** be longer than the app's own deadline for the hub call (M3, at most 10 seconds), so an answer that comes in time is kept, and **MUST** be at most 30 seconds (`T_ACK_MAX_MS`). - `T_connect` is at most 10 minutes. - `T_idle` is the app's; 30 minutes is recommended. Long dormancy is the app's; 30 days is recommended. **What each state answers** (**MUST** wherever the app implements the state): | Method | in flight | handoff | live | dormant | ended | revoked | |---|---|---|---|---|---|---| | any request | HTTP 404, state unchanged | (rows below) | (rows below) | (rows below) | HTTP 404 | 403 `RevokedAnswer` | | `initialize` | 404 | served, commits the connection; since 0.12 only if it holds the [binding](#the-binding), else 404, state unchanged | served if it holds the binding, else 404 | served if it holds the binding (does not wake), else 404 | 404 | `RevokedAnswer` | | `ping`, `tools/list` | 404 | served | served | served | 404 | `RevokedAnswer` | | `tools/call` | 404 | tool error `pairing` | app data | core tools: the idle shapes; other tools: tool error `idle` | 404 | `RevokedAnswer` | | other methods (`resources/*`, `prompts/*`) | 404 | JSON-RPC -32000, `data: { error: "pairing", message }` | as the app serves them | JSON-RPC -32000, `data: { error: "idle", message }` | 404 | `RevokedAnswer` | | notifications | 404 | ignored (202) | served (202) | served (202), does not wake | 404 | `RevokedAnswer` | The first row covers every request to the grant's URL, whatever its method, including a `GET`, a `DELETE` or a body that does not parse. A 404 leaves the state unchanged. `RevokedAnswer` is 403 with the secret URL, as in [revoke from the app](https://apc.tineira.com/docs/spec#revoke-from-the-app). No answer in handoff or dormant carries `attention`, `then`, an `apc_link` offer or a presence event. **The tool errors** are `{ error: "pairing", message }` (the person has not finished pairing) and `{ error: "idle", message }` (the person is away from the app), carried in both `structuredContent` and `content[0].text` (as JSON), with `isError: true` (`DockGrantErrorAnswer`). **The idle shapes** are **MUST** for an app that sleeps: - `get_current_view` answers `{ view: null, focus: null, idle: true, note }` (`idleCurrentView`). - `wait_for_focus` answers `{ focus: null, timed_out: false, page_open: false, idle: true, note }` at once (`idleWaitForFocus`). - An answer without `idle` (an app before 0.10) reads as unavailable or page closed, as before. Dormant returns no data, and is distinct from revoked, unavailable and page closed. **The transitions:** - **`initialize` fails closed.** It **MUST NOT** return a result unless the move out of handoff has committed. On a persistence failure it answers JSON-RPC -32603 or HTTP 500, so the hub's introduction fails where the person sees it. - **The commit out of handoff is conditional.** It happens only if the grant is neither revoked nor ended, in the same atomic step. If Cancel or an end won the race, `initialize` answers by the state that won: `RevokedAnswer` or 404. - **The acknowledgement's move is conditional too.** The move from in flight to handoff happens only if the grant is neither ended (by a give-back or `T_ack`) nor revoked, in the same atomic step. - **A served call** is a `tools/call` that returned app data in the live state. `ping`, `tools/list`, `initialize` and the `pairing` and `idle` errors are not served calls. - **Wake actions** are authenticated actions of the grant's own user on the app's page: a page heartbeat, which **MUST** be sent at least every `T_idle / 2` while the page is open, or a confirmed drop. Agent traffic (`initialize`, `ping`, `tools/list`, `tools/call`) never wakes a grant and never extends it. - **Cancel revokes.** Cancel, on the waiting card, is allowed only in handoff, before any served call; afterwards the grant answers `RevokedAnswer`. The check and the revoke are one atomic step, so Cancel never revokes a live grant or one that has served a call, and every tool handler re-checks revoke after its work and before it returns data ([revoke from the app](https://apc.tineira.com/docs/spec#revoke-from-the-app)). A Dock grant serves app data only while live: after the acknowledgement **and** a committed `initialize`, and while not dormant, ended or revoked. ### One pending pairing There is one pending pairing per (user, hub, agent), at the app and at the hub (H3). - **Before the acknowledgement**, a new drop may replace the pending consent, with a new nonce and a new code. The stale Allow fails closed (`consent_expired`). A second Allow while the first waits on the hub gets `pairing_in_progress`. - **After the acknowledgement and before the committed `initialize`**, a drop calls `/apc/confirm`. On `pending` with the app's own stored expiry still ahead, the page shows the **same** code and the time left: no new consent and no new code. The drop's target replaces the pending pin. - On `not_paired`, or once the stored expiry has passed, the app ends the grant and requests a fresh Connect through `/apc/connect`. A hub answers `not_paired` for a pairing it holds as ended, too. - The app cannot tell "waiting for the code" from "the code was accepted and the hub is introducing": both answer `pending`, and the app shows the same code for both. While the hub is introducing, the dock's own page says it is connecting and takes no code; a code typed then does not count against the five wrong codes. - On `paired` before the app has seen `initialize`, the grant stays in handoff. The page hides the code and says it is connecting, and the drop's target is pinned once the grant is live. Only `initialize` moves the state, never a `confirm` answer. - **The page treats its stored expiry as the truth.** It stops showing the code past it (the countdown and what the page says then are [the UX guide's](https://apc.tineira.com/docs/ux#the-handoff-card)). ### The app and the hub call What an app that implements the Dock profile or still serves any Dock grant **MUST** do around the drop and the hub call (`DockAppRequirement`, M1 to M13): - **M1. Allowlist.** Parse the drop's `hub` with `new URL`. Refuse anything unparsable, not `https:` (except a declared local-dev origin), or carrying userinfo, a path other than `/`, a query or a fragment. Compare `url.origin` for exact equality with a constant allowlist, on the drop **and** again on the Allow. Otherwise answer `hub_not_allowed`, with no consent and no grant. - **M2. Redirects.** Never follow a redirect. Call the hub with `redirect: "manual"` (or `"error"` where the runtime implements it: Cloudflare Workers does not, and throws a `TypeError` before sending anything), and refuse any 3xx, an `opaqueredirect` or `response.redirected`. - **M3. Time limit.** One deadline, at most 10 seconds (`HUB_CALL_DEADLINE_MS`), covers the headers and the whole body. - **M4. Byte cap**, at most 8 KiB (`HUB_ANSWER_MAX_BYTES`). A `content-length` that is present must be ASCII digits only (`/^\d+$/`) and at most the cap, or the answer is refused before it is read. The decoded stream is cut at the cap. An absent `content-length` is not refused. The declared and decoded lengths are never compared, because of `gzip`. - **M5. No lock across the call.** No database transaction or row lock is held across the hub call. One drop, Allow or confirm runs at a time per (user, hub, agent), across instances (an advisory lock and a partial unique index will do). - **M6. Owner-session endpoints** (the drop, the Connect consent and its Allow, the heartbeat, Cancel) need the owner's authenticated session, and every state change is a `POST` with the media type `application/json`. A request that carries `Origin` is refused unless it equals the app's **configured** public origin (behind a proxy, the deployment configures its external origin; the app never derives it from the request URL). A request whose `Sec-Fetch-Site` is `cross-site` or `same-site` is refused. A request with neither header comes from a client that is not a browser (Pulse for Windows, say) and is taken on the session alone: a browser always sends `Origin` on a cross-origin `POST`, so a hostile page cannot strip it, and `application/json` across origins needs a CORS preflight the app never grants. A heartbeat may be a WebSocket; its handshake follows the same `Origin` rule. - **M7. `/apc/revoke`**, as [above](#the-hub-gives-a-grant-back-post-appapcrevoke). - **M8. `apc.json`** lists `dock` only when the app can pair right now (its configuration is present), computed per request or cached 60 seconds at most (a `max-age` of 60 or less). - **M9.** The app sends hub requests to the parsed `url.origin` of M1, never to the raw `hub` string. - **M10, M11, M12** (since 0.12): [the binding](#the-binding), for apps implementing Dock or still serving any Dock grant; M12 covers every non-Dock grant, including Direct grants, regardless of current pairability. - **M13** (since 0.13). An app offering Dock **MUST** publish a fragment-free `dock_connect` on its own origin. Its GET **MUST** answer 200, never a 3xx, with `Referrer-Policy: no-referrer`, and load no third-party script. A synchronous same-origin `
` script, or an inline one, **MUST** read `#apc_connect` and clear it with `history.replaceState` before any other script or redirect. It **MUST** keep the ticket only in `sessionStorage` before sending the person to log in. Its consent **SHOULD** show the signed-in account. A drop with no link **MUST** call `/apc/connect`, never `/apc/pair` with a drop ticket against a 0.13 hub. The temporary 0.12 fallback was permitted only on HTTP 404 from `/apc/connect`, with the same M1 to M4 guards, until one release after the hub cut; that permission ends at 1.0.0. An expired connect link says: “This link expired. Drop the agent again, or use Connect an app in your dock.” ### The hub's duties What a hub **MUST** do (`DockHubRequirement`; the reference hub follows them). `@tineira/apc-conformance` (`hubConformance`) checks the app-visible hub MUSTs (`apc.json` and `H7`, malformed-body ticket preservation, `PAIR-2` and `CODE-2` never-echoed / normalized / codeless when required, `H1`–`H3` excluding pairing-cap accounting, `H5` HTTP 404 tombstone and re-pair, and redirect refusal) in process against an `ApcHubAdapter` (`apps/dock/test/hub-conformance.test.ts` runs it against the reference hub, including `exerciseAgent` and `requiresPairingCode`). Rules that need the dock UI (`CODE-2`'s "never shows" in dock state/sockets, `DROP-1` no secret in the drag, and `TM-1` trust warnings and markings for unverified apps), pairing-cap accounting in `H3`/`H5`, and agent-tool relays (`H4`, `H5`'s `relay()`, `H6`, plus `exerciseAgent` hooks if omitted by another hub) are **reference behaviour, not conformance-tested in 1.0** and are proven by the reference hub's own tests (`apps/dock/test`). All of these MUSTs bind every hub all the same. The sentences of H4 about the hub's own `views[]` and `wait_for_focus` describe [the hub's tools](https://apc.tineira.com/docs/spec#the-hubs-tools), which 1.0 does not freeze; what a hub does with an app's `pairing` and `idle` answers is frozen. - **H1.** The hub sends `initialize` on a grant's MCP URL only after the dock owner approved the pairing with the code, and sends no `initialize`, `tools/list` or `tools/call` before that. While approving, the dock takes no code. - **H2.** `/apc/confirm` expires overdue pending requests before it answers, so an expired request answers `not_paired`. - **H3.** `/apc/pair` replaces an unapproved pending request for the same agent and app origin rather than keeping two. Unapproved means no correct code has been accepted yet: H3 never replaces an approving or paired one. The replaced request does not count toward the hub's pairing cap. The hub gives its URL back (`/apc/revoke`) after answering `/apc/pair`, asynchronously, and only when that URL differs from the new request's. The new request's wrong-code count starts at 0, since it carries a new code from a fresh consent. - **H4.** The hub relays `{ error: "pairing" }` and `{ error: "idle" }` as tool errors: verbatim for verified apps, inside the untrusted envelope for unverified ones. It carries `idle: true` per app in `get_current_view`'s `views[]`. It keeps an idle flag per app, unverified apps included, cleared by the next answer that lacks `idle`. An app's idle answer never ends the hub's wait early and never reads as page closed. When every app is idle, `wait_for_focus` answers `{ focus: null, timed_out: false, page_open: false, idle: true, note }`, saying the apps are asleep and wake when the person opens them, not that the person left. With a mixed fleet, the answer names the apps that are asleep, and the hub waits as usual. - **H5.** A 404 from a pairing that was introduced, or is in handoff, is reported as `pairing_ended` ("drop the agent on the app again"), never as `app_unreachable`. The hub keeps an `ended` tombstone, like `revoked`: outside the cap, deleted on a re-pair, and `relay()` and `decide()` on it answer `pairing_ended`, not `unknown_app` or `unknown_pairing`. - **H6.** The hub's instructions and `guide` say what the errors mean. `idle`: the person is away from that app; tell them, and do not retry. `pairing`: the person has not finished pairing yet; wait, or tell them. - **H7.** The copy of an app's `apc.json` used for a pairing decision is at most 60 seconds old: the hub fetches it fresh on `/apc/pair`, or honours a `max-age` of 60 or less. A 5xx or unreachable `apc.json` never falls back to a stale copy that lists `dock`: the pairing is refused (`apc_json_unreachable`). - **H8** (since 0.12). [The binding](#the-binding): every `initialize` names the pairing and its agent. - **H9** (since 0.13). `/apc/pair` **MUST** accept only a connect ticket minted for this app origin and agent by an owner-approved connect request. A drop ticket is `ticket_not_for_pairing`; a connect ticket for another origin or agent is `ticket_origin_mismatch`. Neither refusal spends the ticket. - **H10** (since 0.13). A connect ticket **MUST** be minted only by an owner-authenticated approve of a connect request, and returned only in that response, inside the `dock_connect` URL. No unauthenticated route and no state broadcast exposes it. ### The binding Since 0.12. The pairing code proves that the dock's owner read a code. The binding proves that the grant the hub introduces itself to is the one this app handed to this pairing, for this agent: a URL the app did not hand to that pairing (a Direct grant, another pairing's grant, a copied URL) never goes live at an app implementing Dock or still serving any Dock grant under 0.12 or later. - **H8.** The hub **MUST**, on every `initialize` it sends to a grant (the introduction, its retries, and every later one), put in `params._meta` the pairing's `pairing_id` under `apc.tineira.com/pairing_id` (`APC_PAIRING_ID_META`) and its agent's handle under `apc.tineira.com/agent` (`APC_AGENT_META`), for every app, verified or not, and **MUST** answer `/apc/pair` with `binding: "pairing_id"`. A `pairing_id` is 22 to 64 of `A–Z a–z 0–9 _ -`, holds at least 128 random bits, is unique across every dock the hub runs, never changes while its pairing exists, and authorizes nothing at the hub. Neither value is a secret: the agent handle is public (it is in the drag), and the app had the `pairing_id` already, from its own acknowledgement. What makes the check hold is that the app compares them with what it stored from its own call, which nobody else can write. - **M10.** Whether a grant is a Dock grant **MUST** come from the app's own record of how it made the grant, written when it made it: never from its URL, the request, its client or the keys above. On the acknowledgement, in the same atomic step as the move out of in flight, the app **MUST** store with the grant the hub's origin, the agent, the `pairing_id`, and whether `binding` was declared. They never change. The hub's origin is context (which hub the binding came from), not a check: the `initialize` names no hub. The app reads the keys from the same parsed body it gates on, never from a later parse or an SDK handler. - **M11.** On a Dock grant in handoff, live or dormant, an `initialize` **MUST** get HTTP 404, its state unchanged, when its `apc.tineira.com/pairing_id` or `apc.tineira.com/agent` is present and is not exactly what the app stored for the grant (a value of another type or form included), or, on a grant whose `binding` was declared, when it is in handoff and carries no `pairing_id`. A missing value is otherwise served: a grant from before 0.12, a hub before 0.12 and a hub rolled back keep working. An app that allows more than one hub **SHOULD** also refuse a missing `pairing_id` on a declared grant in every state. Every `initialize` in a request counts: in a batch, or without an `id`. Revoked, ended and in flight answer first, as before. - **M12.** At an app that implements the Dock profile or still serves any Dock grant, on every non-Dock grant, including a Direct grant, a request carrying an `initialize` with either key, whatever its value, **MUST** get HTTP 404 before any other answer, revoked included, and the grant is unchanged. This duty applies even while `dock` is absent from the app's `apc.json` under M8 and during a hub's 60-second cache window; it never depends on current pairability. Only an app that does not implement Dock and holds no Dock grant owes no M12 refusal; it **MAY** refuse anyway. - At an app implementing Dock or still serving any Dock grant, the 404s of M11 and M12 **SHOULD** carry `{ "error": "pairing_mismatch" }`; a hub reads only that exact token. The app never shows the keys to its page or puts them in an answer, and **SHOULD NOT** log them. - A grant whose record holds no `pairing_id` (made before the app implemented 0.12) is checked on its agent alone. - Apps on 0.10 to 0.12 retain confirming and relaying **existing** pairings for at least six months after 1.0. A **new** Dock first pairing needs 0.13, including origin-bound Connect. Older apps ignore the binding keys where their version permits; an app that validates `params._meta` strictly must accept the two keys. ### The derived secret (optional) An app may derive a dock grant's secret instead of storing a random one. The recipe is optional; what holds either way is that the hash and salt the app stores cannot rebuild the secret. - **Inputs:** K, at least 32 random bytes; `