@tineira/apc-protocol 0.8.0 → 0.9.0

package/CHANGELOG.md

@@ -4,6 +4,26 @@ This file records the contract that an app and an agent share in Agent Pointed C
 
 The standard has its own semver, `APC_STANDARD_VERSION` in `@tineira/apc-protocol`, separate from the software release. It stays 0.x while the standard is a draft and becomes 1.0.0 when it is published. The version of the paper (V1, the apc.tineira.com demo) is not a 1.x of this standard. Every change to the contract adds an entry here and bumps the constant: a new minor (or, from 1.0, a major) version. A patch (0.7.0 to 0.7.1) never changes the contract; it fixes the packages or the wording, so an app that implements 0.7.0 implements every 0.7.x.
 
+## 0.9.0 (draft, 2026-11-12)
+
+The pairing code: on the Dock profile the app's consent shows a code, and the dock's Allow requires it (TIN-859). A drag can be put on any page, and anyone who runs a dock can mint tickets for their own agent; before, they could lure an app's owner into a drop and an Allow and get their own agent paired with the owner's data. In `packages/protocol/src/core.ts`, `packages/server/src/consent.ts`, `packages/server/src/hub-client.ts`, `packages/conformance` and DESIGN.md section 12.
+
+### Pairing
+
+- **The app shows a pairing code with its consent, and sends it to the hub.** Six characters of Crockford base32 (`PAIRING_CODE_LENGTH`, `PAIRING_CODE_ALPHABET`, 30 bits), new for every consent, shown as `K7M-4P2` (`formatPairingCode`) with the warning to type it only in the person's own dock. After the Allow the app sends it raw in `pairing_code` of `POST {hub}/apc/pair` (`DockPairRequest`). An app that implements 0.9 **must** send it. The code never goes over MCP, in a URL, to `/apc/confirm` or anywhere but the app owner's page and that one request.
+- **The hub keeps it and answers `pairing_code: "required"`** (`PAIRING_CODE_ACK`, `DockPairAnswer`), never shows it (not in the dock's state, a broadcast or any answer), and checks the body before it spends the ticket: a `pairing_code` that is present but not a code (`null`, `""`, a number) is `invalid_pairing_code`. Only an absent key is a pairing without a code; a hub may refuse those (`pairing_code_required`).
+- **The dock owner's Allow needs the code.** The hub compares it in constant time (`pairingCodesMatch`) with what the app sent; a missing or malformed code is refused without counting; a wrong one counts, `wrong_pairing_code` with `attempts_left`, and the fifth (`PAIRING_CODE_MAX_ATTEMPTS`) removes the request and gives the grant back (`pairing_code_refused`). A request with a code that nobody approves goes after `PAIRING_CODE_TTL_MS` (120 s), its grant given back; one without keeps the old ten minutes. Deny and unpair need no code. Typing is forgiving: case, spaces and dashes are ignored, O reads as 0 and I or L as 1 (`normalizePairingCode`).
+- **The app keeps a grant only on the acknowledgement**: a non-redirected HTTP 200 with `ok: true`, `pairing_code: "required"` and a string `pairing_id`. A hub's own refusal is HTTP 400 with `ok: false` and its error. Anything else (another status, a redirect, a missing acknowledgement, no answer) and the app deletes the grant before it answers its page (`hub_refused`, `hub_unreachable`, `hub_ignores_pairing_code`, `HubCallError`). `/apc/confirm` is believed the same way: 200, `ok: true`, `status` `"pending"` or `"paired"`.
+- **A drag's ticket lives 240 s** (`TICKET_TTL_MS`; it was 60 s), longer than the app's two-minute consent, so the person has the time to read the card.
+- **What the app shows after the Allow** (reference behaviour, not a MUST): the code again, the time left, and Cancel, until the hub connects (its first `initialize` on the grant) or the grant goes; if the person's own dock never asks for that code, the agent was someone else's.
+
+### Packages
+
+- `@tineira/apc-server`: `DockConsent.ask` returns `{ nonce, pairing_code }`, and `take` is replaced by `takeConsent`, which returns `{ ok: true, pairing_code }` or `{ ok: false }` (no boolean to test by mistake): every caller has to show the code and send it. New: `newPairingCode`, and `pairWithHub` / `confirmWithHub` (`redirect: "error"`, a 10 s limit, the rules above).
+- `@tineira/apc-conformance`: `standInHub`, a hub to pair with in process, faithful on tickets, the code, wrong codes, expiry, the give-back and the acknowledgement, with broken modes (`no_ack`, `redirect`, `error_500`). An adapter on the Dock profile gives `dock: { hub, drop }`, required of an app that claims 0.9.0 or later (as `page.mobile` since 0.6). New checks: the consent shows a well-formed code and the app sends that code; every consent shows a new code; a hub that does not acknowledge, redirects or says yes with a 500 holds no grant; five wrong codes or the code's expiry give the grant back; the right code pairs.
+
+An app that implements 0.8 keeps pairing with a hub in its default mode (`when_sent`), without a code, until the operator requires one; to claim 0.9.0 it shows and sends the code and fails closed on the hub's answer.
+
 ## 0.8.0 (draft, 2026-11-12)
 
 The core tools made robust, from a second implementation in use, and the Direct profile freed from how the agent authenticates (TIN-839, TIN-667). In `packages/protocol/src/core.ts`, `manifest.ts`, `packages/server/src/tools.ts`, `waits.ts`, `packages/conformance` and DESIGN.md section 21.

package/README.md

@@ -8,7 +8,7 @@ The contract an app and an agent share in Agent Pointed Context: wire types, the
 npm i @tineira/apc-protocol@next
 ```
 
-Pre-releases go out on the `next` tag while the standard is 0.x; the package's version follows the standard's (0.8.x ships APC 0.8).
+Pre-releases go out on the `next` tag while the standard is 0.x; the package's version follows the standard's (0.9.x ships APC 0.9).
 
 ```ts
 import { APC_STANDARD_VERSION, focusAttrs, parseApcManifest } from "@tineira/apc-protocol";
@@ -41,7 +41,7 @@ What every APC app implements, whichever way agents reach it ([`src/core.ts`](sr
 What belongs to a profile, not to the core:
 
 - **Direct** (the agent connects to the app's own MCP URL): a grant per agent, its secret URL, the list where the person makes and names agents.
-- **Dock** (the agent connects once, to a hub): the drop (`application/x-apc-agent`, the handle and the ticket), consent in the app (checked by the app's server, never its page alone: 0.7, `DockConsent` in `@tineira/apc-server`), `POST {hub}/apc/pair` (the hub reads the app's `apc.json` first), `POST {hub}/apc/confirm` on every drop, and `POST {app}/apc/revoke`, the hub giving a grant back.
+- **Dock** (the agent connects once, to a hub): the drop (`application/x-apc-agent`, the handle and the ticket), consent in the app (checked by the app's server, never its page alone: 0.7, `DockConsent` in `@tineira/apc-server`), with a pairing code the dock's Allow requires (0.9, `PAIRING_CODE_LENGTH`), `POST {hub}/apc/pair` (the hub reads the app's `apc.json` first; the app keeps its grant only on the hub's acknowledgement of the code, `pairWithHub`), `POST {hub}/apc/confirm` on every drop, and `POST {app}/apc/revoke`, the hub giving a grant back.
 
 Whatever it offers, an app publishes `apc.json` (below).
 

package/dist/core.d.ts

@@ -17,7 +17,8 @@
  *   a grant for a dock agent it holds none for only on a request that proves the person allowed it on the
  *   app's page just now (the reference apps: a single-use nonce the page shows its consent with,
  *   `DockConsent` in `@tineira/apc-server`), whatever the page last loaded. A page that missed a revoke must not
- *   pair without asking.
+ *   pair without asking. Since APC 0.9 the consent shows a pairing code, and the dock's Allow requires it
+ *   (`PAIRING_CODE_LENGTH`, below).
  *
  * The core is the same on both, and per grant: the hub is one more holder of a grant.
  *
@@ -218,6 +219,85 @@ export declare const APC_MOBILE_VIEWPORT: {
     readonly width: 375;
     readonly height: 812;
 };
+/**
+ * The pairing code (Dock profile, APC 0.9). A drag can be put on a page by anyone: whoever runs a dock can
+ * mint tickets for their own agent and lure the app's owner into a drop and an Allow. So a pairing is
+ * approved in the dock only with a code that only the app's owner sees.
+ *
+ * - **The app makes it** with its consent nonce: `PAIRING_CODE_LENGTH` characters of `PAIRING_CODE_ALPHABET`
+ *   (Crockford base32, 30 bits), new for every consent (`newPairingCode` and `DockConsent` in
+ *   `@tineira/apc-server`), and shows it on its consent card, formatted `K7M-4P2` (`formatPairingCode`). After
+ *   the Allow, the app sends it raw (`K7M4P2`) in `pairing_code` of `POST {hub}/apc/pair` (`DockPairRequest`).
+ *   An app that implements 0.9 **must** send it. It never goes anywhere else: not over MCP, not in a URL,
+ *   not to `/apc/confirm`.
+ * - **The hub keeps it** with the pending pairing, never shows it (not in the dock's state, not in a
+ *   broadcast, not in any answer) and answers a pairing that carries one with `pairing_code: "required"`
+ *   (`PAIRING_CODE_ACK`, `DockPairAnswer`). It checks the body before it spends the ticket: a `pairing_code`
+ *   that is present but does not normalize (`null`, `""`, a number) is `invalid_pairing_code`. Only an absent
+ *   key is a pairing without a code (an app from before 0.9); a hub may refuse those too
+ *   (`pairing_code_required`).
+ * - **The dock owner types it** to approve: the hub compares it, in constant time, with the one the app sent.
+ *   A wrong one counts; after `PAIRING_CODE_MAX_ATTEMPTS` the request goes and the grant is given back
+ *   (`pairing_code_refused`). A request with a code that nobody approves goes after `PAIRING_CODE_TTL_MS`, its
+ *   grant given back. A match clears the code. Deny and unpair need no code.
+ * - **The app keeps a grant only on the acknowledgement**: a non-redirected HTTP 200 with `ok: true`,
+ *   `pairing_code: "required"` and a string `pairing_id` (`pairWithHub` in `@tineira/apc-server`). Anything
+ *   else (another status, a redirect, a missing acknowledgement, no answer) and the app deletes the grant
+ *   before it answers its page: a hub that does not check codes never holds a grant (`hub_ignores_pairing_code`).
+ *
+ * The drag's ticket lives `TICKET_TTL_MS` (240 s since 0.9; 60 s before), longer than the app's consent, so
+ * the person has the time to read the card.
+ */
+export declare const PAIRING_CODE_LENGTH = 6;
+/** Crockford base32: no I, L, O or U, so a code reads out loud without doubt. */
+export declare const PAIRING_CODE_ALPHABET = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+/** How long a pending pairing with a code waits for the dock owner, from `/apc/pair`. */
+export declare const PAIRING_CODE_TTL_MS = 120000;
+/** Wrong codes a hub takes for one pairing; the last one removes it. */
+export declare const PAIRING_CODE_MAX_ATTEMPTS = 5;
+/** What a hub that keeps the code answers in `pairing_code`. */
+export declare const PAIRING_CODE_ACK = "required";
+/** How long a drag's ticket works (APC 0.9: 240 s). */
+export declare const TICKET_TTL_MS = 240000;
+/** Why a hub refuses a pairing or an approval over its code. */
+export type PairingCodeError = "invalid_pairing_code" | "pairing_code_required" | "wrong_pairing_code" | "pairing_code_refused";
+/** Why an app did not keep a grant after asking a hub to pair (`pairWithHub`), when the hub gave no reason of its own. */
+export type HubCallError = "hub_unreachable" | "hub_refused" | "hub_ignores_pairing_code";
+/**
+ * A code as typed or sent, made canonical: case, spaces and dashes are ignored, O reads as 0 and I or L as 1.
+ * Null unless the result is `PAIRING_CODE_LENGTH` characters of `PAIRING_CODE_ALPHABET`.
+ */
+export declare function normalizePairingCode(input: unknown): string | null;
+/** How a code is shown to a person: `K7M4P2` as `K7M-4P2`. For display only; the wire and storage keep it raw. Anything that is not a code is returned untouched, never shaped like one. */
+export declare function formatPairingCode(code: string): string;
+/** Whether two normalized codes are the same, in time that does not depend on where they differ. */
+export declare function pairingCodesMatch(expected: string, given: string): boolean;
+/** `POST {hub}/apc/pair`: what an app sends after the person's Allow (Dock profile). `pairing_code` is raw, 6 characters. */
+export interface DockPairRequest {
+    ticket: string;
+    agent: string;
+    app: {
+        name: string;
+        origin: string;
+    };
+    mcp_url: string;
+    /** Required of an app that implements 0.9; absent only from an app before it. */
+    pairing_code?: string;
+}
+/** The hub's answer to `/apc/pair`: HTTP 200 with the acknowledgement, or HTTP 400 with the reason. */
+export type DockPairAnswer = {
+    ok: true;
+    pairing_id: string;
+    status: "pending";
+    agent: {
+        name: string;
+        icon: string | null;
+    };
+    pairing_code: typeof PAIRING_CODE_ACK;
+} | {
+    ok: false;
+    error: string;
+};
 /** The other path: Direct for Dock and Dock for Direct. */
 export declare function oppositePath(path: ApcProfile): ApcProfile;
 /**

package/dist/core.js

@@ -76,6 +76,75 @@ export function isRevokedAnswer(body) {
  */
 export const APC_MOBILE_MEDIA = "(pointer: coarse), (max-width: 640px)";
 export const APC_MOBILE_VIEWPORT = { width: 375, height: 812 };
+/**
+ * The pairing code (Dock profile, APC 0.9). A drag can be put on a page by anyone: whoever runs a dock can
+ * mint tickets for their own agent and lure the app's owner into a drop and an Allow. So a pairing is
+ * approved in the dock only with a code that only the app's owner sees.
+ *
+ * - **The app makes it** with its consent nonce: `PAIRING_CODE_LENGTH` characters of `PAIRING_CODE_ALPHABET`
+ *   (Crockford base32, 30 bits), new for every consent (`newPairingCode` and `DockConsent` in
+ *   `@tineira/apc-server`), and shows it on its consent card, formatted `K7M-4P2` (`formatPairingCode`). After
+ *   the Allow, the app sends it raw (`K7M4P2`) in `pairing_code` of `POST {hub}/apc/pair` (`DockPairRequest`).
+ *   An app that implements 0.9 **must** send it. It never goes anywhere else: not over MCP, not in a URL,
+ *   not to `/apc/confirm`.
+ * - **The hub keeps it** with the pending pairing, never shows it (not in the dock's state, not in a
+ *   broadcast, not in any answer) and answers a pairing that carries one with `pairing_code: "required"`
+ *   (`PAIRING_CODE_ACK`, `DockPairAnswer`). It checks the body before it spends the ticket: a `pairing_code`
+ *   that is present but does not normalize (`null`, `""`, a number) is `invalid_pairing_code`. Only an absent
+ *   key is a pairing without a code (an app from before 0.9); a hub may refuse those too
+ *   (`pairing_code_required`).
+ * - **The dock owner types it** to approve: the hub compares it, in constant time, with the one the app sent.
+ *   A wrong one counts; after `PAIRING_CODE_MAX_ATTEMPTS` the request goes and the grant is given back
+ *   (`pairing_code_refused`). A request with a code that nobody approves goes after `PAIRING_CODE_TTL_MS`, its
+ *   grant given back. A match clears the code. Deny and unpair need no code.
+ * - **The app keeps a grant only on the acknowledgement**: a non-redirected HTTP 200 with `ok: true`,
+ *   `pairing_code: "required"` and a string `pairing_id` (`pairWithHub` in `@tineira/apc-server`). Anything
+ *   else (another status, a redirect, a missing acknowledgement, no answer) and the app deletes the grant
+ *   before it answers its page: a hub that does not check codes never holds a grant (`hub_ignores_pairing_code`).
+ *
+ * The drag's ticket lives `TICKET_TTL_MS` (240 s since 0.9; 60 s before), longer than the app's consent, so
+ * the person has the time to read the card.
+ */
+export const PAIRING_CODE_LENGTH = 6;
+/** Crockford base32: no I, L, O or U, so a code reads out loud without doubt. */
+export const PAIRING_CODE_ALPHABET = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+/** How long a pending pairing with a code waits for the dock owner, from `/apc/pair`. */
+export const PAIRING_CODE_TTL_MS = 120_000;
+/** Wrong codes a hub takes for one pairing; the last one removes it. */
+export const PAIRING_CODE_MAX_ATTEMPTS = 5;
+/** What a hub that keeps the code answers in `pairing_code`. */
+export const PAIRING_CODE_ACK = "required";
+/** How long a drag's ticket works (APC 0.9: 240 s). */
+export const TICKET_TTL_MS = 240_000;
+/**
+ * A code as typed or sent, made canonical: case, spaces and dashes are ignored, O reads as 0 and I or L as 1.
+ * Null unless the result is `PAIRING_CODE_LENGTH` characters of `PAIRING_CODE_ALPHABET`.
+ */
+export function normalizePairingCode(input) {
+    if (typeof input !== "string" || input.length > 32)
+        return null;
+    const code = input.toUpperCase().replace(/[\s-]/g, "").replace(/O/g, "0").replace(/[IL]/g, "1");
+    if (code.length !== PAIRING_CODE_LENGTH)
+        return null;
+    for (const c of code)
+        if (!PAIRING_CODE_ALPHABET.includes(c))
+            return null;
+    return code;
+}
+/** How a code is shown to a person: `K7M4P2` as `K7M-4P2`. For display only; the wire and storage keep it raw. Anything that is not a code is returned untouched, never shaped like one. */
+export function formatPairingCode(code) {
+    const raw = normalizePairingCode(code);
+    return raw ? `${raw.slice(0, 3)}-${raw.slice(3)}` : code;
+}
+/** Whether two normalized codes are the same, in time that does not depend on where they differ. */
+export function pairingCodesMatch(expected, given) {
+    if (expected.length !== PAIRING_CODE_LENGTH || given.length !== PAIRING_CODE_LENGTH)
+        return false;
+    let diff = 0;
+    for (let i = 0; i < PAIRING_CODE_LENGTH; i++)
+        diff |= expected.charCodeAt(i) ^ given.charCodeAt(i);
+    return diff === 0;
+}
 /** The other path: Direct for Dock and Dock for Direct. */
 export function oppositePath(path) {
     return path === "direct" ? "dock" : "direct";

package/dist/version.d.ts

@@ -7,4 +7,4 @@
  * and becomes 1.0.0 when the standard is published. Every change to the
  * contract adds an entry to `packages/protocol/CHANGELOG.md` and bumps this.
  */
-export declare const APC_STANDARD_VERSION = "0.8.0";
+export declare const APC_STANDARD_VERSION = "0.9.0";

package/dist/version.js

@@ -7,4 +7,4 @@
  * and becomes 1.0.0 when the standard is published. Every change to the
  * contract adds an entry to `packages/protocol/CHANGELOG.md` and bumps this.
  */
-export const APC_STANDARD_VERSION = "0.8.0";
+export const APC_STANDARD_VERSION = "0.9.0";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tineira/apc-protocol",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Agent Pointed Context (APC): the contract an app and an AI agent share. Wire types, the target grammar, the core, apc.json and the version of the standard.",
   "keywords": [
     "apc",