@tineira/apc-server 0.8.0 → 0.9.0

package/dist/consent.d.ts

@@ -5,18 +5,36 @@ import type { ApcKv } from "./kv.js";
  * the app's own page. The page cannot be the judge of that: it decides from the state it last loaded, and
  * a page that missed an update (a revoke, a dock that forgot the pairing) would pair without asking. So the
  * server decides: asked to pair an agent it holds no grant for, it answers `consent_required` with a nonce
- * (`ask`); the page shows its consent with that nonce, and sends it back with the person's Allow; the server
- * makes the grant only when it takes the nonce (`take`): once, for the same dock and agent, within
- * `DOCK_CONSENT_TTL_MS`.
+ * and a pairing code (`ask`); the page shows its consent with both, and sends the nonce back with the
+ * person's Allow; the server makes the grant only when it takes the nonce (`takeConsent`): once, for the same
+ * dock and agent, within `DOCK_CONSENT_TTL_MS`. Taking it gives back the pairing code (APC 0.9), which the app
+ * sends to the hub in `/apc/pair` and the dock owner must type to approve.
  *
  * The nonce lives in the app's own storage, reached only through the person's own session (the app's owner
  * cookie), so it is kept as is: it proves the request went through the page's consent, not who sent it.
- * `ask` and `take` are synchronous: in a Durable Object nothing runs between the check and the write.
+ * `ask` and `takeConsent` are synchronous: in a Durable Object nothing runs between the check and the write.
  */
 /** The answer an app gives when it needs the person's yes on its page first. */
 export declare const CONSENT_REQUIRED = "consent_required";
-/** How long a consent nonce works: longer than a drag's ticket (60 s), which ends the pairing anyway. */
+/** How long a consent nonce and its pairing code work: two minutes, within a drag's ticket (240 s, APC 0.9). */
 export declare const DOCK_CONSENT_TTL_MS = 120000;
+/** What `ask` gives the page: the nonce to send back with the Allow, and the code to show (raw; format it to show it). */
+export interface ConsentAsk {
+    nonce: string;
+    pairing_code: string;
+}
+/** What `takeConsent` gives: the code to send to the hub, or nothing (no `true` to test by mistake). */
+export type ConsentTaken = {
+    ok: true;
+    pairing_code: string;
+} | {
+    ok: false;
+};
+/**
+ * A new pairing code (APC 0.9): `PAIRING_CODE_LENGTH` characters of Crockford base32, 5 random bits each (a
+ * byte masked to 31, which is unbiased since 256 is a multiple of 32): 30 bits. Raw, as sent and stored.
+ */
+export declare function newPairingCode(): string;
 export declare class DockConsent {
     private kv;
     private clock;
@@ -24,8 +42,11 @@ export declare class DockConsent {
         now?: () => number;
     });
     private now;
-    /** A new nonce for the page to show its consent with, for this dock and agent. Expired ones go first. */
-    ask(hub: string, agent: string): string;
-    /** True once: the nonce was asked for this dock and agent and has not expired. Used or not, it goes. */
-    take(nonce: unknown, hub: string, agent: string): boolean;
+    /** A new nonce and pairing code for the page to show its consent with, for this dock and agent. Expired ones go first. */
+    ask(hub: string, agent: string): ConsentAsk;
+    /**
+     * Once: the nonce was asked for this dock and agent and has not expired, and here is the pairing code it was
+     * shown with, to send to the hub. Used or not, it goes.
+     */
+    takeConsent(nonce: unknown, hub: string, agent: string): ConsentTaken;
 }

package/dist/consent.js

@@ -1,25 +1,34 @@
+import { PAIRING_CODE_ALPHABET, PAIRING_CODE_LENGTH } from "@tineira/apc-protocol";
 /**
  * Consent in the app, checked by the app's server (the Dock profile, APC 0.7, `core.ts` in @tineira/apc-protocol).
  * A dock agent dropped on an app that holds no grant for it gets one only after the person allowed it on
  * the app's own page. The page cannot be the judge of that: it decides from the state it last loaded, and
  * a page that missed an update (a revoke, a dock that forgot the pairing) would pair without asking. So the
  * server decides: asked to pair an agent it holds no grant for, it answers `consent_required` with a nonce
- * (`ask`); the page shows its consent with that nonce, and sends it back with the person's Allow; the server
- * makes the grant only when it takes the nonce (`take`): once, for the same dock and agent, within
- * `DOCK_CONSENT_TTL_MS`.
+ * and a pairing code (`ask`); the page shows its consent with both, and sends the nonce back with the
+ * person's Allow; the server makes the grant only when it takes the nonce (`takeConsent`): once, for the same
+ * dock and agent, within `DOCK_CONSENT_TTL_MS`. Taking it gives back the pairing code (APC 0.9), which the app
+ * sends to the hub in `/apc/pair` and the dock owner must type to approve.
  *
  * The nonce lives in the app's own storage, reached only through the person's own session (the app's owner
  * cookie), so it is kept as is: it proves the request went through the page's consent, not who sent it.
- * `ask` and `take` are synchronous: in a Durable Object nothing runs between the check and the write.
+ * `ask` and `takeConsent` are synchronous: in a Durable Object nothing runs between the check and the write.
  */
 /** The answer an app gives when it needs the person's yes on its page first. */
 export const CONSENT_REQUIRED = "consent_required";
-/** How long a consent nonce works: longer than a drag's ticket (60 s), which ends the pairing anyway. */
+/** How long a consent nonce and its pairing code work: two minutes, within a drag's ticket (240 s, APC 0.9). */
 export const DOCK_CONSENT_TTL_MS = 120_000;
 const PREFIX = "consent:";
 function randomHex(bytes) {
     return [...crypto.getRandomValues(new Uint8Array(bytes))].map((b) => b.toString(16).padStart(2, "0")).join("");
 }
+/**
+ * A new pairing code (APC 0.9): `PAIRING_CODE_LENGTH` characters of Crockford base32, 5 random bits each (a
+ * byte masked to 31, which is unbiased since 256 is a multiple of 32): 30 bits. Raw, as sent and stored.
+ */
+export function newPairingCode() {
+    return [...crypto.getRandomValues(new Uint8Array(PAIRING_CODE_LENGTH))].map((b) => PAIRING_CODE_ALPHABET[b & 31]).join("");
+}
 export class DockConsent {
     kv;
     clock;
@@ -30,7 +39,7 @@ export class DockConsent {
     now() {
         return this.clock();
     }
-    /** A new nonce for the page to show its consent with, for this dock and agent. Expired ones go first. */
+    /** A new nonce and pairing code for the page to show its consent with, for this dock and agent. Expired ones go first. */
     ask(hub, agent) {
         const now = this.now();
         for (const [key, raw] of this.kv.list(PREFIX)) {
@@ -43,24 +52,30 @@ export class DockConsent {
             }
         }
         const nonce = `cn_${randomHex(16)}`;
-        this.kv.put(`${PREFIX}${nonce}`, JSON.stringify({ hub, agent, expires_at: now + DOCK_CONSENT_TTL_MS }));
-        return nonce;
+        const pairing_code = newPairingCode();
+        this.kv.put(`${PREFIX}${nonce}`, JSON.stringify({ hub, agent, expires_at: now + DOCK_CONSENT_TTL_MS, pairing_code }));
+        return { nonce, pairing_code };
     }
-    /** True once: the nonce was asked for this dock and agent and has not expired. Used or not, it goes. */
-    take(nonce, hub, agent) {
+    /**
+     * Once: the nonce was asked for this dock and agent and has not expired, and here is the pairing code it was
+     * shown with, to send to the hub. Used or not, it goes.
+     */
+    takeConsent(nonce, hub, agent) {
         if (typeof nonce !== "string" || !/^cn_[0-9a-f]{32}$/.test(nonce))
-            return false;
+            return { ok: false };
         const key = `${PREFIX}${nonce}`;
         const raw = this.kv.get(key);
         if (!raw)
-            return false;
+            return { ok: false };
         this.kv.delete(key);
         try {
             const row = JSON.parse(raw);
-            return row.hub === hub && row.agent === agent && row.expires_at > this.now();
+            if (row.hub !== hub || row.agent !== agent || row.expires_at <= this.now() || typeof row.pairing_code !== "string")
+                return { ok: false };
+            return { ok: true, pairing_code: row.pairing_code };
         }
         catch {
-            return false;
+            return { ok: false };
         }
     }
 }

package/dist/hub-client.d.ts

@@ -0,0 +1,58 @@
+import { type DockPairRequest } from "@tineira/apc-protocol";
+/**
+ * An app's calls to a dock's hub, server to server (the Dock profile; APC 0.9): `pairWithHub` after the
+ * person's Allow, `confirmWithHub` on every later drop. Both fail closed. A call never follows a redirect
+ * (`redirect: "error"`: the app's hub list is its trust anchor, and a redirect would hand the grant and the
+ * pairing code to another host), gives up after `timeoutMs` (10 s by default), and believes only these
+ * answers:
+ *
+ * - **HTTP 200** with `ok: true` and, for a pairing, the acknowledgement `pairing_code: "required"` and a
+ *   string `pairing_id`; for a confirm, `status` `"pending"` or `"paired"`.
+ * - **HTTP 400** with `ok: false` and an `error` in the hub's vocabulary (`/^[a-z_]{1,64}$/`): the hub's
+ *   own refusal, passed on.
+ *
+ * Anything else is a refusal of the app's own: `hub_unreachable` (no answer, a time limit, a redirect the
+ * runtime refused), `hub_ignores_pairing_code` (a yes without the acknowledgement: a hub that would not check
+ * the code), `hub_refused` (any other status, a redirect that came through, JSON that is not an answer).
+ * On any refusal after `/apc/pair` the app deletes the grant it made, before it answers its page: a grant is
+ * kept only when the hub said it holds the code.
+ */
+export interface HubCallOptions {
+    /** How the app reaches the hub; the global fetch by default. */
+    fetch?: typeof fetch;
+    /** Milliseconds before the call gives up: 10 000 by default. */
+    timeoutMs?: number;
+}
+/** The agent as the hub names it, checked: strings or null, nothing else. */
+export interface HubAgent {
+    name: string | null;
+    icon: string | null;
+}
+export type PairWithHubResult = {
+    ok: true;
+    pairing_id: string;
+    status: "pending";
+    agent: HubAgent;
+} | {
+    ok: false;
+    error: string;
+};
+export type ConfirmWithHubResult = {
+    ok: true;
+    status: "pending" | "paired";
+    agent: HubAgent;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * `POST {hub}/apc/pair` with the pairing code (APC 0.9). `{ ok: true }` only on HTTP 200 with the
+ * acknowledgement; on anything else the caller deletes the grant it made before it answers.
+ */
+export declare function pairWithHub(hub: string, body: DockPairRequest, options?: HubCallOptions): Promise<PairWithHubResult>;
+/** `POST {hub}/apc/confirm` on a drop of an agent the app holds a grant for: whether the hub still pairs them. */
+export declare function confirmWithHub(hub: string, body: {
+    ticket: string;
+    agent: string;
+    mcp_url: string;
+}, options?: HubCallOptions): Promise<ConfirmWithHubResult>;

package/dist/hub-client.js

@@ -0,0 +1,69 @@
+import { PAIRING_CODE_ACK } from "@tineira/apc-protocol";
+const HUB_ERROR = /^[a-z_]{1,64}$/;
+const agentOf = (raw) => {
+    const a = raw && typeof raw === "object" ? raw : {};
+    return { name: typeof a.name === "string" ? a.name : null, icon: typeof a.icon === "string" ? a.icon : null };
+};
+async function post(hub, path, body, options) {
+    const send = options.fetch ?? ((...args) => fetch(...args));
+    let response;
+    try {
+        response = await send(`${hub}${path}`, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify(body),
+            redirect: "error",
+            signal: AbortSignal.timeout(options.timeoutMs ?? 10_000),
+        });
+    }
+    catch {
+        return { error: "hub_unreachable" };
+    }
+    // A fetch that followed a redirect anyway (or gave the redirect itself back) is not the hub answering.
+    if (response.redirected || response.type === "opaqueredirect" || (response.status >= 300 && response.status < 400)) {
+        await response.body?.cancel().catch(() => { });
+        return { error: "hub_refused" };
+    }
+    try {
+        const parsed = (await response.json());
+        return { status: response.status, body: parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : null };
+    }
+    catch {
+        return { status: response.status, body: null };
+    }
+}
+/** The hub's own refusal (HTTP 400, `ok: false`, an error in its words), or null. */
+function refusal(a) {
+    return a.status === 400 && a.body?.ok === false && typeof a.body.error === "string" && HUB_ERROR.test(a.body.error) ? a.body.error : null;
+}
+/**
+ * `POST {hub}/apc/pair` with the pairing code (APC 0.9). `{ ok: true }` only on HTTP 200 with the
+ * acknowledgement; on anything else the caller deletes the grant it made before it answers.
+ */
+export async function pairWithHub(hub, body, options = {}) {
+    const a = await post(hub, "/apc/pair", body, options);
+    if ("error" in a)
+        return { ok: false, error: a.error };
+    const refused = refusal(a);
+    if (refused)
+        return { ok: false, error: refused };
+    if (a.status !== 200 || a.body?.ok !== true)
+        return { ok: false, error: "hub_refused" };
+    if (a.body.pairing_code !== PAIRING_CODE_ACK)
+        return { ok: false, error: "hub_ignores_pairing_code" };
+    if (typeof a.body.pairing_id !== "string" || !a.body.pairing_id)
+        return { ok: false, error: "hub_refused" };
+    return { ok: true, pairing_id: a.body.pairing_id, status: "pending", agent: agentOf(a.body.agent) };
+}
+/** `POST {hub}/apc/confirm` on a drop of an agent the app holds a grant for: whether the hub still pairs them. */
+export async function confirmWithHub(hub, body, options = {}) {
+    const a = await post(hub, "/apc/confirm", body, options);
+    if ("error" in a)
+        return { ok: false, error: a.error };
+    const refused = refusal(a);
+    if (refused)
+        return { ok: false, error: refused };
+    if (a.status !== 200 || a.body?.ok !== true || (a.body.status !== "pending" && a.body.status !== "paired"))
+        return { ok: false, error: "hub_refused" };
+    return { ok: true, status: a.body.status, agent: agentOf(a.body.agent) };
+}

package/dist/index.d.ts

@@ -9,3 +9,4 @@ export * from "./direct.js";
 export * from "./links.js";
 export * from "./apc-json.js";
 export * from "./consent.js";
+export * from "./hub-client.js";

package/dist/index.js

@@ -9,3 +9,4 @@ export * from "./direct.js";
 export * from "./links.js";
 export * from "./apc-json.js";
 export * from "./consent.js";
+export * from "./hub-client.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tineira/apc-server",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Agent Pointed Context (APC) for an app's server: the MCP tools of the core, the attention envelope, presence, revoke, apc.json, Direct grants, Dock consent and apc_link.",
   "keywords": [
     "apc",
@@ -40,7 +40,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@tineira/apc-protocol": "^0.8.0"
+    "@tineira/apc-protocol": "^0.9.0"
   },
   "peerDependencies": {
     "@modelcontextprotocol/sdk": "^1.32.1",