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) 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, 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, new in Dock 1.0, changes from APC's text, the changelog and the 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 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 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 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).

Since 0.9 the consent shows a 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). 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.

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:

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 (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). 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), 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 (M1 to M9), and the grant is in flight 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.

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 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.

StateBeginsEnds
in flightthe Allowthe 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
handoffthe acknowledgementthe first initialize whose connection is committed
livethe committed initializedormancy, revoke or end
dormant (SHOULD)T_idle after the last wake action (live grants only)the next wake action
endedT_connect after the acknowledgement with no committed initialize (MUST); a give-back (/apc/revoke); long dormancynever
revokedthe owner's Revoke, or Cancelnever

The time limits (T_ACK_MAX_MS, T_CONNECT_MAX_MS and the recommended times in @tineira/apc-protocol):

What each state answers (MUST wherever the app implements the state):

Methodin flighthandofflivedormantendedrevoked
any requestHTTP 404, state unchanged(rows below)(rows below)(rows below)HTTP 404403 RevokedAnswer
initialize404served, commits the connection; since 0.12 only if it holds the binding, else 404, state unchangedserved if it holds the binding, else 404served if it holds the binding (does not wake), else 404404RevokedAnswer
ping, tools/list404servedservedserved404RevokedAnswer
tools/call404tool error pairingapp datacore tools: the idle shapes; other tools: tool error idle404RevokedAnswer
other methods (resources/*, prompts/*)404JSON-RPC -32000, data: { error: "pairing", message }as the app serves themJSON-RPC -32000, data: { error: "idle", message }404RevokedAnswer
notifications404ignored (202)served (202)served (202), does not wake404RevokedAnswer

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. 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:

The transitions:

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).

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):

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, which 1.0 does not freeze; what a hub does with an app's pairing and idle answers is frozen.

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.

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.

What secures the Dock #

The Dock's security is the 0.9 pairing code plus a secret URL over TLS. There is no end-to-end encryption, and the hub sees what it relays.

The pairing code gates the honest hub's approval, and that hub's initialize is the owner's yes (H1). The code never gates the app's data path. Against a hub that breaks H1, or against someone holding the URL, the URL is the credential, as in 0.9. No app can detect a breach of H1: hub conformance and the operator's allowlist are the controls.

Since 0.12 the binding ties the hub's initialize to the app's own /apc/pair call for that agent. Since 0.13 the origin-bound Connect step closes the relay of a victim's drop ticket through a real app account: the drop only asks, and the dock opens the app's declared page in the dock owner's own session with a new connect ticket. The pairing code still guards against the reverse case, an attacker-owned dock luring an app owner. The dock MUST show the app's host on every request. The person types a code only from their own account and never reads it out to someone else.

The page never sees the MCP URL or the secret, and the code is shown only on the owner's page and sent only in /apc/pair. APC covers pointing only: confirmations and approvals of what an agent does are outside the standard.

From apc_link in APC's specification: the section entire but for its notice of deprecation.

An app that offers both profiles shows the same agent on both paths as one.

Dock in apc.json #

The rules of apc.json that are about the Dock profile. The document itself, its path grammar, its matching rules and its every other key are APC's (apc.json).

From apc.json in APC's specification: the key dock_connect, the profile words of an app and a hub, M8 in profiles, the rule on mcp.path as it binds a hub, and the answer to a dock agent on a Direct-only app.

A dock agent dropped on an app that offers only Direct is answered, never lost: the page tells the person that it connects agents directly and links its connect page (direct.connect), and pairs nothing (the reference sentence, directOnlyNote, is in the UX guide). A page that cannot read its own apc.json pairs nothing either.

From mcp.endpoints in APC's specification: a hub among the readers before 0.11, the profile word dock in an entry, matching for dock, a file that narrows, and the vectors whose profile is dock.

mcp.path may stay beside it for readers before 0.11, which still cover all of it. An app keeps it while any such reader exists (a hub, the browser extension, its own bundled @tineira/apc-web); one that wants the narrower rule for every reader leaves it out and accepts that older readers refuse the file.

Profile words other than direct and dock are left out of an entry one by one, and so is dock on an exact path: a Dock grant is one URL per grant. An entry may list a profile the top-level profiles does not (an app that is not pairing right now, M8); it covers nothing for that profile.

Matching. A reader MUST cover an MCP URL for a profile R (direct or dock; a hub pairing a Dock app checks dock) only when all of these hold:

  1. It is an absolute http/https URL on the file's origin, with no user or password.
  2. The string holds no ?, # or %, and is exactly origin + path as a URL parser writes it back: no dot segment, backslash, upper-case host, written default port or encoding.
  3. The top-level profiles and a usable entry both list R, and either:

A file that narrows does not end pairings already made; the app revokes them.

{
  "shared-urls": {"name":"Example","standard":"0.11.0","origin":"https://www.cars.example","profiles":["direct"],"mcp":{"path":"/api/","endpoints":[{"path":"/api/mcp","profiles":["direct"]},{"path":"/api/ops/mcp","profiles":["direct"]}]},"direct":{"connect":"https://www.cars.example/connect"}},
  "split": {"name":"Example","standard":"0.11.0","origin":"https://ledger.example","profiles":["direct","dock"],"mcp":{"path":"/mcp/","endpoints":[{"path":"/mcp","profiles":["direct"]},{"path":"/mcp/{secret}","profiles":["dock"]}]},"direct":{"connect":"https://ledger.example/connect"}},
  "split-not-pairing": {"name":"Example","standard":"0.11.0","origin":"https://ledger.example","profiles":["direct"],"mcp":{"path":"/mcp/","endpoints":[{"path":"/mcp","profiles":["direct"]},{"path":"/mcp/{secret}","profiles":["dock"]}]},"direct":{"connect":"https://ledger.example/connect"}},
  "named-siblings": {"name":"Example","standard":"0.11.0","origin":"https://ops.example","profiles":["direct","dock"],"mcp":{"endpoints":[{"path":"/mcp/operations-console","profiles":["direct"]},{"path":"/mcp/tenant-admin-console/mcp","profiles":["direct"]},{"path":"/mcp/future-console-entry/","profiles":["direct"]},{"path":"/mcp/later-feature-route","profiles":["direct"],"methods":["POST"]},{"path":"/mcp/{secret}","profiles":["dock"]}]},"direct":{"connect":"https://ops.example/connect"}},
  "direct-template": {"name":"Example","standard":"0.11.0","origin":"https://orders.example","profiles":["direct","dock"],"mcp":{"endpoints":[{"path":"/mcp/{secret}","profiles":["direct"]}]},"direct":{"connect":"https://orders.example/connect"}},
  "unknown-key": {"name":"Example","standard":"0.11.0","origin":"https://orders.example","profiles":["direct","dock"],"mcp":{"endpoints":[{"path":"/mcp/{secret}","profiles":["dock"],"requires":"pairing_code"}]},"direct":{"connect":"https://orders.example/connect"}},
  "path-only": {"name":"Example","standard":"0.11.0","origin":"https://ledger.example","profiles":["direct","dock"],"mcp":{"path":"/mcp/"},"direct":{"connect":"https://ledger.example/connect"}}
}
FileURLProfileSharedCoveredWhy
splithttps://ledger.example/mcp/AbCdEfGhIjKlMnOpQrStUvdocknoyesa grant's secret under the dock template
splithttps://ledger.example/mcpdocknonothe hub never pairs a shared URL
splithttps://ledger.example/mcp/AbCdEfGhIjKlMnOpQrStUv/xdocknonoa secret is one segment
splithttps://ledger.example/mcp/AbCdEfGhIjKlMnOdocknono15 characters is too short for a secret
splithttps://ledger.example/mcp/aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaadocknono129 characters is too long for a secret
splithttps://ledger.example/mcp/abcdefgh.ijklmnopdocknonono dot in a secret
splithttps://ledger.example/mcp/abcdefgh~ijklmnopdocknonono tilde in a secret
splithttps://ledger.example/mcp/AbCdEfGhIjKlMnOpQrStUv?docknonoan empty query
splithttps://ledger.example/mcp/AbCdEfGhIjKlMnOpQrStUv#docknonoan empty fragment
splithttps://ledger.example/mcp/AbCdEfGhIjKlMnOpQrStUv?a=1docknonoa query
splithttps://ledger.example/mcp/AbCdEfGhIjKlMnOpQrStUv/docknonoa trailing slash
splithttps://ledger.example/mcp/AbCdEfGhIjKlMnOpQrStUv;x=1docknonoa matrix parameter
splithttps://ledger.example/mcp/AbCdEfGhIjKlMnOpQrStUv|docknonoa pipe
splithttps://ledger.example//mcp/AbCdEfGhIjKlMnOpQrStUvdocknonoa double slash
splithttps://ledger.example/mcp/./AbCdEfGhIjKlMnOpQrStUvdocknonoa dot segment
splithttps://ledger.example/mcp/%41AbCdEfGhIjKlMnOpQrStUvdocknonoany percent-encoding
splithttps://ledger.example/mcp/AbCdEfGhIjKlMnOpQrStUv/..%2fdocknonoencoded traversal
splithttps://ledger.example/mcp/%2e%2e%2fadminabcdefghijdocknonoencoded dots and slash
splithttps://ledger.example/mcp\AbCdEfGhIjKlMnOpQrStUvdocknonoa backslash
splithttps://ledger.example/Mcp/AbCdEfGhIjKlMnOpQrStUvdocknonothe path is case-sensitive
splithttps://LEDGER.example/mcp/AbCdEfGhIjKlMnOpQrStUvdocknonoan upper-case host is not written as parsed
splithttps://ledger.example:443/mcp/AbCdEfGhIjKlMnOpQrStUvdocknonoa written default port
splithttps://u:p@ledger.example/mcp/AbCdEfGhIjKlMnOpQrStUvdocknonocredentials
splitblob:https://ledger.example/mcp/AbCdEfGhIjKlMnOpQrStUvdocknonoa blob: URL has the origin, not the scheme
splithttps://evil.example/mcp/AbCdEfGhIjKlMnOpQrStUvdocknonoanother origin
splitnot a urldocknononot a URL
split-not-pairinghttps://ledger.example/mcp/AbCdEfGhIjKlMnOpQrStUvdocknonothe top level does not list dock: not pairing right now
shared-urlshttps://www.cars.example/api/mcpdocknonothe app does not offer dock
named-siblingshttps://ops.example/mcp/AbCdEfGhIjKlMnOpQrStUvdocknoyesa grant's secret
named-siblingshttps://ops.example/mcp/operations-consoledocknonoexact wins: a sibling the file names
named-siblingshttps://ops.example/mcp/Operations-Consoledocknonoexact wins without ASCII case
named-siblingshttps://ops.example/mcp/tenant-admin-consoledocknonoexact wins: the fixed parent of a deeper entry
named-siblingshttps://ops.example/mcp/future-console-entrydocknonoexact wins: named by an entry this reader drops (trailing slash)
named-siblingshttps://ops.example/mcp/later-feature-routedocknonoexact wins: named by an entry this reader drops (unknown key)
direct-templatehttps://orders.example/mcp/0123456789abcdef0123456789abcdefdocknonoa Direct-only template never pairs
unknown-keyhttps://orders.example/mcp/AbCdEfGhIjKlMnOpQrStUvdocknonoan entry with an unknown key is dropped whole
path-onlyhttps://ledger.example/mcp/AbCdEfGhIjKlMnOpQrStUv?a=1docknoyesno endpoints: the 0.10 rule under mcp.path, unchanged

New in Dock 1.0 #

The hub's trust model #

From the hub's trust model in APC's specification: the warning, the limits, the blocklist and the kill switch, and, with the definitions it is written in (which APC keeps too), the rule that an unverified app uses HTTPS on a domain name. Untrusted marking stays in APC.

What a hub does about apps it does not know. The rules below are the reference hub's; a hub that follows them protects agents the same way.

Verified and unverified apps #

A hub's verified apps are the ones its operator lists. Any other app is unverified. Its identity is its domain: its id, and so its tool prefix, comes from its host (evil.example gives evil_example__get_order), always holds a _ and never __, so it can never take a verified app's prefix or page. What it calls itself is kept only as declared_name. An unverified app MUST use HTTPS on a domain name (no IP address, no single-label or localhost host), and its redirects are not followed.

The warning #

An unverified app pairs only after the person approves the dock's warning for its domain: the domain first, Not verified, what the app calls itself marked as its own word, and the risk (your agent will read whatever this app tells it, which could lead it to move data out of your other apps), with Deny as the default button (how the dock lays it out beyond that is the UX guide's). The approval is once per domain per dock; Deny, Unpair or Remove withdraws it. The hub, not the page, enforces it.

Limits #

The reference hub reads at most 1 MiB of each answer from a verified app and 256 KiB from an unverified one, with a time limit that covers the body; it keeps an unverified app's view only under 8 KB, its tool schemas under 8 KB, its descriptions cut at 1 KB, 32 tools at most; it takes its pin only when well formed and on its own origin; it takes no app's pin dated ahead of its clock, verified or not; it follows no app's redirect; and it holds 20 app pairings per dock at most (too_many_apps).

The blocklist and the kill switch #

A hub may block domains (a domain covers its subdomains): a blocked app cannot pair (app_blocked), and a pairing made before reads as blocked and is never called again. The reference hub also has a kill switch that closes it to every unverified app at once; verified apps are untouched.

Dock clauses in APC's kept sections #

Sentences of sections APC keeps that speak of a hub, a dock or a Dock grant. APC 1.2 marked the Dock words in them; here they are whole.

From reading what you do not know in APC's specification: a hub's answers.

So that a minor version can add without breaking anyone, every reader MUST ignore what it does not know:

From the core in APC's specification.

A hub is one more holder of a grant, so the core is the same for it.

From attention in APC's specification: the parenthetical on a Dock grant.

(on a Dock grant, only a live one: no answer in handoff or dormant carries it, see what each state answers)

From wait events in APC's specification.

From get_current_view in APC's specification.

A dormant dock grant (since 0.10) answers { view: null, focus: null, idle: true, note }: see the grant's states.

From wait_for_focus in APC's specification.

From revoke from the app in APC's specification.

Every agent in the app's agent bar, Direct or Dock, has Revoke. It holds in the app alone and at once: the app calls nobody, so it works with the hub down.

From mobile in APC's specification: the rule, which holds on both profiles.

On a phone there is no dock window, extension or desktop pet to drag from, so the agent in the app's page is the only way to point it. In a viewport that matches (pointer: coarse), (max-width: 640px) (APC_MOBILE_MEDIA), on both profiles:

This is interoperability, not presentation: with no mouse and no dock window, a page that hides the agents or cannot be tapped leaves the person with no way to point, so the conformance suite checks it (page.mobile).

From the agent in the page in APC's specification.

The UX guide describes the reference pattern (the pet, the header, the pin badge, the states, motion, colour, phones, the pairing cards); it is non-normative, nothing in it is required to interoperate, and @tineira/apc-web is its reference implementation.

From the Direct profile in APC's specification: a grant's stable id.

From the hub's tools in APC's specification: the two spans that name the Dock profile and H4; the section stays in APC, non-normative.

From the browser extension in APC's specification: its sentence on a Direct-only app.

On a Direct-only app that does not answer dock drops itself, the extension tells the person to connect directly.

Error codes #

From error codes in APC's specification: the rows on a Dock grant and apc_link of what an app answers an agent, the four tables of the Dock profile with the paragraph on /apc/reader/status, and the two rows of what a hub answers an agent that serve H4 and H5.

A code marked reference is what the reference software answers there; another implementation may answer another code for the same case and still conform.

An app, to an agent on a grant (the core, both profiles)

CodeWhenWhere
pairinga tool call (tool error) or another method (JSON-RPC -32000) on a Dock grant in handoffthe grant's states
idlea tool other than a core tool, or another method, on a dormant Dock grantthe grant's states
pairing_mismatchat an app implementing Dock or still serving any Dock grant, the body (SHOULD) of the HTTP 404 an initialize gets when it does not hold the grant's binding (M11), or carries either binding key on a grant that is not a Dock grant (M12)the binding
link_refusedapc_link refused, with a reason: unknown_code, expired, used, same_connection, same_path, not_offered or already_linkedapc_link

An app, to its own page, on a drop or an Allow (Dock)

CodeWhenWhere
consent_requirednot an error: the agent needs the person's consent, with its nonce and pairing codeconsent in the app
hub_not_allowedthe drop's hub fails the allowlist (M1)the app and the hub call
consent_expiredan Allow whose consent a newer drop replaced, or that ran outone pending pairing
pairing_in_progressan Allow while another Allow of that agent waits on the hubone pending pairing
hub_ignores_pairing_codethe hub answered 200 without the code's acknowledgement; the grant is deletedpairing
hub_unreachable, hub_refusedreference (pairWithHub, confirmWithHub): no answer in time; any answer that is not an acknowledgementthe app and the hub call
invalid_dropreference (parseDockDrop): a drop that is not { v: 1, agent, hub, ticket }the drop

A hub, to an app (HTTP 400 with { ok: false, error }, on /apc/pair and /apc/confirm)

CodeWhenWhere
invalid_pairing_codepairing_code is present and not a code; the ticket is not spentpairing
pairing_code_required/apc/pair without pairing_code (an app before 0.9)the pairing code
ticket_expiredreference: the ticket is unknown, spent, out of time, or another agent'sthe drop
invalidreference: the body lacks ticket, agent or mcp_url
dock_expiredreference: the ticket's dock is gone
app_not_allowedreference: the MCP URL is not on the app's origin, the hub is closed to unverified apps, or the host is not a domain nameverified and unverified apps
https_requiredreference: an unverified app over http:verified and unverified apps
app_blockedthe app's domain is blocked (on /apc/confirm too)the blocklist
app_host_too_long, app_id_takenreference: an unverified app's host gives no usable tool prefixverified and unverified apps
too_many_appsthe dock already holds as many pairings as it takeslimits
apc_json_missing, apc_json_redirected, apc_json_unreachable, apc_json_invalid, apc_json_wrong_originthe app's apc.json is missing, redirected, out of reach (H7), unreadable, or names another origin (ApcJsonRefusal)apc.json
dock_not_offeredthe app's apc.json does not list "dock"apc.json
mcp_url_not_declaredthe app's apc.json does not cover mcp_url for dockmcp.endpoints
not_paired/apc/confirm: the dock no longer pairs this agent with this grant, or holds the pairing as endedevery drop

Connect and reader routes (HTTP 400 {ok:false,error} on every refusal below; owner authentication retains the existing middleware's 403/404)

CodeRoutes and meaning
invalid/apc/connect: malformed body (an app body without app.origin included); owner create: empty or malformed host or agent
dock_expired/apc/connect, /apc/pair: dock no longer exists
ticket_expired/apc/connect, /apc/pair: absent, expired, consumed ticket or removed agent (an expired connect ticket included, on /apc/connect and /apc/confirm too); /apc/connect also refuses an agent mismatch
ticket_not_for_pairingdrop ticket on /apc/pair; live connect ticket on /apc/connect or /apc/confirm; every call to the obsolete /apc/reader; no ticket is spent on these refusals
ticket_origin_mismatch/apc/pair: connect ticket bound to a different origin or agent, unspent
too_many_requests/apc/connect, owner create: request limits or the per-ticket attempt cap reached, drop ticket unspent
reader_not_allowedreader /apc/connect, /apc/reader/status, owner reader approve: extension origin not allowed
app_not_allowed, https_required, app_blockedapp /apc/connect, owner create/approve: origin verdict refused
apc_json_missing, apc_json_redirected, apc_json_unreachable, apc_json_invalid, apc_json_wrong_origin, dock_not_offeredapp /apc/connect, owner create: manifest refusal; missing dock_connect is apc_json_invalid
not_foundowner approve/deny: absent, expired, denied or already consumed connect request
warning_required, invalid_action, unknown_agentowner connect actions: unacknowledged warning, unknown action, or agent removed
forbiddenowner routes: absent/wrong owner cookie or cross-origin/site request (HTTP 403)
dock_expiredowner routes: cookie no longer opens a live dock (HTTP 404)

/apc/reader/status returns HTTP 200 denied for a malformed, unknown, expired, consumed or other-origin claim. It never exposes a token for one of these claims.

A hub, to the dock's owner, on an approval (the dock's page)

CodeWhenWhere
pairing_code_required, invalid_pairing_codereference: Allow with no code, or with one that is not a code; neither counts as a wrong codethe pairing code
wrong_pairing_codea wrong code, with attempts_leftthe pairing code
pairing_code_refusedthe fifth wrong code: the request goes and its grant is given backthe pairing code
warning_requiredreference: an unverified app approved before its warning wasthe warning
unknown_pairingreference: the request is gone (expired, replaced or decided meanwhile)one pending pairing

A hub, to an agent (outside the 1.0 freeze, except H4 and H5)

CodeWhenWhere
pairing, idlean app's answer, relayed (H4)the hub's duties
pairing_endeda pairing the hub introduced answered 404 (H5)the hub's duties

Versioning and compatibility #

From versioning and compatibility in APC's specification: the hub's duties to apps of older versions, and the promises to apps that go with the hubs they bind.

Changes from APC's text #

Every change made to the text copied from APC's specification (APC 1.3.0, commit 527c3d5). The line is the line of APC's apps/site/src/docs/pages/spec.md at that commit. Each copied line is a whole line of APC, or such a line after the changes below for its number, and nothing else (apps/dock-site/test/words.test.ts checks it).

Words #

Each change of words, so that the sentence is true in a separate document.

LineAPC's wordsHereWhy
680which this release endswhich APC 1.0.0 ends"This release" is APC 1.0.0; in this document it would name Dock 1.0, which ends nothing.
681When a new major version shipsWhen a new major version of APC shipsHere "a new major version" would read as one of Dock. The promise is to apps of APC's previous major, kept by the reference hub when APC 2.0 ships.

Lines copied in part #

Where a block copies only part of a line, the part runs from the first words given to the last, and the rest of the line stays in APC. A part set as a list item gains only the list's dash.

LineFromToWhy
424- profiles: "direct",dock: { pair, confirm }.The words APC 1.2 marks in profiles (a hub's); the rest of the line, the 1.3 SHOULD on profile words, stays in APC.
424Since 0.10 anat most (M8).The sentence APC 1.2 marks (M8).
425- mcp.path: asegment after it.The rule as it binds a hub (APC 1.2 marks "a hub pairs"), with its subject; the last sentence, on a Direct app's shared URL, stays in APC.
446mcp.path may stayrefuse the file.The readers before 0.11, a hub among them (APC 1.2 marks "a hub, "); the sentences before it, the 0.11 reader's MUST among them, stay in APC.
455Profile words otherfor that profile.The rule APC 1.1 marks (dock on an exact path) and the sentence APC 1.2 marks (M8); the reading rules around them stay in APC.
465A file thatapp revokes them.The sentence APC 1.2 marks; the duties of a {secret} parent stay in APC.
83A hub issame for it.The sentence APC 1.2 marks; the core stays in APC.
115(on a Dockwhat each state answers)The parenthetical APC 1.2 marks; attention stays in APC.
140A dormant dockthe grant's states.The sentence APC 1.2 marks; get_current_view stays in APC.
165The person letsthe dock (Dock).The bullet whose words APC 1.2 marks (", or a new drop with consent in the app and in the dock (Dock)"), so they have a sentence to stand in.
176This is interoperability,checks it (page.mobile).The sentence whose words APC 1.2 marks ("and no dock window"); the rest of the paragraph stays in APC.
180The UX guideits reference implementation.The sentence whose words APC 1.2 marks (", the pairing cards"); the rest stays in APC.
194A grant MUSTkeyed by it)The sentence whose words APC 1.2 marks (", presence and apc_link"); the rest of the Direct profile stays in APC.
393An app reliesDock profile above.The span APC 1.2 marks; the hub's tools stay in APC, non-normative.
395Since 0.10 itas H4 says.The sentence APC 1.2 marks; the hub's tools stay in APC, non-normative.
576On a Direct-onlyto connect directly.The sentence APC 1.2 marks; the browser extension stays in APC.
582A code markedand still conform.The sentence that says what a code marked reference is, which the copied tables use; the rest stays in APC.
678An older readera major version.The span APC 1.2 marks; the rule of what breaks stays in APC.
679A hub orthat version defines.The span APC 1.2 marks ("A hub or ") in its sentence; the rest stays in APC.
679A hub tellsof that field.The sentence APC 1.2 marks.
683From 1.0, theup, labelled "pre-1.0".The span APC 1.2 marks; the conformance suite's other rules stay in APC.
683Dock first-pairing conformancefloor of 0.13.The sentence APC 1.2 marks.

Changelog #

1.0.0-next.0 #

First publication of the Dock profile as its own protocol: the clauses APC 1.1 and 1.2 marked deprecated, word for word from APC 1.3.0, with the two changes of words a separate document needs and the lines it copies only in part, each listed; who Dock 1.0 binds; and dock_standard. Nothing changes for any party: APC 1.x still carries these clauses.

Licence #

The text of this document is licensed CC BY 4.0, like APC's specification, which most of it copies: you may share and adapt it, for any purpose, with credit to "The Dock protocol, https://dock.tineira.com, Tomas Neira" and, for the text it copies, to "Agent Pointed Context, https://apc.tineira.com/docs, Tomas Neira", a link to the licence, and a note of any changes. Changes from APC's text lists the changes made here. The code of the @tineira/dock-* packages is MIT.