@intentic/sandbox-contract 1.337.0 → 1.339.0

package/src/policy/org-locks.ts

@@ -0,0 +1,173 @@
+import { ORG_SECTIONS, type OrgPolicy, type OrgSection, orgSectionMode } from "../schemas/organisation.js";
+
+// WHICH DAEMON ROUTES AN ORGANISATION'S LOCK COVERS, and the refusal the daemon's middleware hands a request to one of
+// them (docs/architecture/organisations.md). Named route by route rather than by contract group: a group mixes the
+// changes a lock is about with operations it is not (a probe, a reveal, a sign-in being cancelled, a person confirming
+// their own AI-literacy notice), and a lock that broke those would be a lock nobody could live with. A route added
+// later is therefore open until it is listed here, which is the failure a reviewer can see in this file's diff.
+//
+// Names are the contract's own: `group.procedure` for a typed route, `METHOD /path` for a raw one (RAW_ROUTES). The
+// test beside this checks every name against the route tables, so a rename cannot leave a lock pointing at nothing.
+
+interface SectionRoutes {
+    // Refused while the section is locked or hidden: every change the section's page makes.
+    readonly changes: readonly string[];
+    // Refused only while it is hidden: reads that put a value in front of a person, which hiding is meant to stop.
+    readonly reveals?: readonly string[];
+}
+
+export const ORG_SECTION_ROUTES = {
+    models: { changes: ["accounts.start", "accounts.complete", "accounts.rename", "accounts.disconnect"] },
+    agent: {
+        // `privacy.learn` stays open: teaching the shield more values only ever adds protection.
+        changes: [
+            "settings.set",
+            "settings.setAgentDomain",
+            "privacy.setPolicy",
+            "privacy.forget",
+            "safety.setPolicy",
+            "skills.save",
+            "skills.remove",
+        ],
+        reveals: ["privacy.reveal"],
+    },
+    // Rejecting a proposed tool and timing a rebuild stay open: neither changes what the sandbox is made of.
+    environment: {
+        changes: [
+            "POST /environment/approve",
+            "POST /environment/runtime-install",
+            "POST /environment/remove",
+            "POST /engines/channel",
+            "POST /engines/update",
+            "POST /engines/revert",
+        ],
+    },
+    // Secrets and connections share the Secrets page. Asking a named person to release one (`secrets.request`) stays
+    // open: it changes nothing until that person says yes.
+    secrets: {
+        changes: [
+            "secrets.set",
+            "secrets.generate",
+            "secrets.remove",
+            "secrets.setGate",
+            "secrets.removeGate",
+            "secrets.setHosts",
+            "secrets.setPolicy",
+            "capabilities.add",
+            "capabilities.remove",
+            "capabilities.rename",
+            "capabilities.setSecret",
+            "capabilities.sshKey",
+            "capabilities.login",
+        ],
+        reveals: ["secrets.reveal"],
+    },
+    "data-protection": { changes: ["compliance.applyPreset"] },
+    extensions: {
+        changes: [
+            "extensions.create",
+            "extensions.remove",
+            "extensions.setSettings",
+            "extensions.approve",
+            "extensions.setEnabled",
+            "extensions.applyUpdate",
+            "extensions.revert",
+            "extensions.setUpdatePolicy",
+            "extensions.devSet",
+            "extensions.devClear",
+            "extensions.devReload",
+        ],
+    },
+    // Leaving (`DELETE /members/self`) stays open: nobody can be held in a sandbox by a policy.
+    access: { changes: ["POST /members", "DELETE /members"] },
+    areas: { changes: ["areas.save", "areas.remove"] },
+    personas: { changes: ["personas.save", "personas.remove", "personas.savePrompt", "personas.saveSkill", "personas.removeSkill"] },
+    updates: { changes: ["system.autoUpdate", "system.skipUpdate"] },
+} as const satisfies Readonly<Record<OrgSection, SectionRoutes>>;
+
+// Refused on ANY bound sandbox, whatever its sections say: acts by which the sandbox's owner would take the organisation's
+// sandbox away from everyone else in it. Closing the daemon to every browser (what deleting one's account does to each
+// owned sandbox) would leave a department's work unreachable by the colleagues who carry it on; the organisation
+// releases the sandbox first if that is what it wants. Listed under `access`, the part of the sandbox it belongs to.
+export const ORG_BOUND_ROUTES: readonly string[] = ["POST /system/access/disable"];
+
+// Route name → the section it belongs to and whether it is a change or a reveal; built once.
+type Covered = { readonly section: OrgSection; readonly kind: "change" | "reveal" | "bound" };
+const COVERED: ReadonlyMap<string, Covered> = (() => {
+    const covered = new Map<string, Covered>();
+    for (const section of ORG_SECTIONS) {
+        const routes: SectionRoutes = ORG_SECTION_ROUTES[section];
+        for (const name of routes.changes) {
+            covered.set(name, { section, kind: "change" });
+        }
+        for (const name of routes.reveals ?? []) {
+            covered.set(name, { section, kind: "reveal" });
+        }
+    }
+    for (const name of ORG_BOUND_ROUTES) {
+        covered.set(name, { section: "access", kind: "bound" });
+    }
+    return covered;
+})();
+
+// The section a route belongs to, or undefined for one no lock covers.
+export const orgSectionOfRoute = (routeName: string): OrgSection | undefined => COVERED.get(routeName)?.section;
+
+export interface OrgLockRefusal {
+    readonly error: string;
+    readonly reason: "org-locked";
+    readonly section: OrgSection;
+    readonly org: string;
+}
+
+// The refusal for one request, or undefined to let it through. No policy (a personal sandbox) is always undefined:
+// this function is the whole of what an organisation changes about a request, and for a personal sandbox it is nothing.
+export const orgLockRefusal = (policy: OrgPolicy | undefined, routeName: string | undefined): OrgLockRefusal | undefined => {
+    if (policy === undefined || routeName === undefined) {
+        return undefined;
+    }
+    const covered = COVERED.get(routeName);
+    if (covered === undefined) {
+        return undefined;
+    }
+    const mode = orgSectionMode(policy, covered.section);
+    const refused = covered.kind === "bound" || (covered.kind === "change" ? mode !== "open" : mode === "hidden");
+    return refused
+        ? {
+              error: `${policy.orgName} manages this part of the sandbox (${covered.section}); ask your organisation's admin to change it`,
+              reason: "org-locked",
+              section: covered.section,
+              org: policy.orgName,
+          }
+        : undefined;
+};
+
+// A write refused because it would undo an organisation's pinned settings (schemas/organisation.ts `preset`): the
+// preset items it would have loosened, by the ids the data protection page shows them under.
+export interface OrgPinRefusal {
+    readonly error: string;
+    readonly reason: "org-pinned";
+    readonly items: readonly string[];
+    readonly org: string;
+}
+
+export const orgPinRefusal = (policy: Pick<OrgPolicy, "orgName">, items: readonly string[]): OrgPinRefusal => ({
+    error: `${policy.orgName} requires ${items.join(", ")} to stay as it set them; ask your organisation's admin to change it`,
+    reason: "org-pinned",
+    items,
+    org: policy.orgName,
+});
+
+// A grant refused because the organisation keeps its sandboxes to its own members (schemas/organisation.ts
+// `membersOnly`).
+export interface OrgMembersOnlyRefusal {
+    readonly error: string;
+    readonly reason: "org-members-only";
+    readonly org: string;
+}
+
+export const orgMembersOnlyRefusal = (policy: Pick<OrgPolicy, "orgName">): OrgMembersOnlyRefusal => ({
+    error: `${policy.orgName} gives access to its sandboxes only to its own members; ask your organisation's admin to add this person first`,
+    reason: "org-members-only",
+    org: policy.orgName,
+});

package/src/policy/persona-capability.ts

@@ -0,0 +1,57 @@
+// WHETHER A PERSONA LETS A TURN ACT THROUGH ONE CONNECTED CAPABILITY. Pure and shared, because the daemon mounts a turn's
+// tools on this answer (personas/personas.ts `turnPersona`) and the Sandbox ▸ Map view draws who reaches what from it,
+// and two implementations would disagree at exactly the boundary that matters.
+
+// The two fields of a connection the rule reads; structural, so neither side has to hand over its own record type.
+export interface CapabilityRef {
+    readonly id: string;
+    readonly kind: string;
+}
+
+// The persona's shelves the rule reads, fully resolved (PersonaPowersSchema's defaults applied): a list absent means
+// every connection of its kind, an empty one none.
+export interface PersonaShelves {
+    readonly sandbox: boolean;
+    readonly delegate: boolean;
+    readonly connectors?: readonly string[] | undefined;
+    readonly devices?: readonly string[] | undefined;
+    readonly mcp?: readonly string[] | undefined;
+}
+
+/** The kinds that are someone signed in: a site account, and the identity whose browser holds every account born of it. */
+export const isSignedInAccount = (kind: string): boolean => kind === "browser" || kind === "identity";
+
+const listed = (list: readonly string[] | undefined, id: string): boolean => list === undefined || list.includes(id);
+
+/**
+ * Whether a persona carrying these accounts (its `capabilities`) and these shelves may act through a capability. A kind
+ * absent from the switch (an agent runtime, a devops entry, a VPN) passes untouched, so a new kind is never silently
+ * denied.
+ */
+export const personaAllowsCapability = (capability: CapabilityRef, accounts: readonly string[], shelves: PersonaShelves): boolean => {
+    switch (capability.kind) {
+        // The signed-in browsers: the persona's own `capabilities` list, and the field that predates the shelves. Granting
+        // an account (`reddit-work`) grants its hands; granting the identity itself grants the someone.
+        case "browser":
+        case "identity":
+            return accounts.includes(capability.id);
+        // Connector credentials reach the shell; an ungranted id keeps its env vars out of the turn entirely.
+        case "cli":
+            return listed(shelves.connectors, capability.id);
+        // A phone is one of the owner's own devices, on the same shelf as their computers.
+        case "device":
+        case "phone":
+            return listed(shelves.devices, capability.id);
+        case "mcp":
+            return listed(shelves.mcp, capability.id);
+        // Making sandboxes on the owner's account is administering what this one runs beside: the sandbox shelf.
+        case "fleet":
+            return shelves.sandbox;
+        // Another of the owner's sandboxes sits on the devices list beside their computers, picked one by one, and handing
+        // it a task is delegating, as spawning a subagent is.
+        case "link":
+            return shelves.delegate && listed(shelves.devices, capability.id);
+        default:
+            return true;
+    }
+};

package/src/policy/reserved-servers.ts

@@ -41,11 +41,12 @@ export const CONTROL_MCP_SERVERS: ReadonlySet<string> = new Set(
 );
 
 // Capability kinds whose id becomes an MCP server name for the turn, and so whose id must not collide with a daemon
-// server: `mcp`, a core kind that is its own endpoint, and every contributable kind the manifest schema says mints one
+// server: `mcp`, a core kind that is its own endpoint, `link`, whose card is mounted as a server named after it, and
+// every contributable kind the manifest schema says mints one
 // (a device's and a connected browser's peer bridge, a cli card that serves tools), read off the schema's own meaning
 // (`contributedServerMintingKinds`), so a kind that starts minting is refused here without a second list. Other kinds
 // mint accounts, providers or infrastructure, never a `mcp__<id>__` server keyed by the id.
-export const MCP_SERVER_MINTING_KINDS: ReadonlySet<string> = new Set(["mcp", ...contributedServerMintingKinds()]);
+export const MCP_SERVER_MINTING_KINDS: ReadonlySet<string> = new Set(["mcp", "link", ...contributedServerMintingKinds()]);
 
 // Whether adding or renaming a capability of this kind to this id would shadow a daemon server. The one predicate the
 // capability routes consult, so the refusal and this list can't drift.

package/src/policy/tests/org-locks.test.ts

@@ -0,0 +1,92 @@
+import { RAW_ROUTE_LIST } from "../../protocol/raw/raw-routes.js";
+import { SANDBOX_ROUTES, sandboxRouteFor } from "../../index.js";
+import { type OrgPolicy, OrgPolicySchema, orgPinnedGroups, orgUnknownPins } from "../../schemas/organisation.js";
+import { ORG_BOUND_ROUTES, ORG_SECTION_ROUTES, orgLockRefusal, orgPinRefusal, orgSectionOfRoute } from "../org-locks.js";
+
+const policy = (sections: OrgPolicy["sections"]): OrgPolicy => ({ orgId: "org-1", orgName: "Urząd Gminy", version: 3, sections });
+
+describe("org locks", () => {
+    it("names only routes that exist, and never a read as a change", () => {
+        const known = new Map([...SANDBOX_ROUTES, ...RAW_ROUTE_LIST].map((route) => [route.name, route.method]));
+        for (const [section, routes] of Object.entries(ORG_SECTION_ROUTES)) {
+            for (const name of routes.changes) {
+                expect({ section, name, method: known.get(name) }).toEqual({ section, name, method: expect.not.stringMatching(/^(GET|HEAD)$/) });
+            }
+            for (const name of "reveals" in routes ? routes.reveals : []) {
+                expect({ section, name, known: known.has(name) }).toEqual({ section, name, known: true });
+            }
+        }
+    });
+
+    it("lets everything through for a personal sandbox", () => {
+        expect(orgLockRefusal(undefined, "settings.set")).toBeUndefined();
+        expect(orgLockRefusal(undefined, "secrets.reveal")).toBeUndefined();
+    });
+
+    it("refuses a change to a locked section and names the organisation", () => {
+        const refused = orgLockRefusal(policy({ agent: "locked" }), "settings.set");
+        expect(refused).toMatchObject({ reason: "org-locked", section: "agent", org: "Urząd Gminy" });
+        expect(orgLockRefusal(policy({ agent: "locked" }), "secrets.set")).toBeUndefined();
+    });
+
+    it("keeps reveals open while locked and refuses them once hidden", () => {
+        expect(orgLockRefusal(policy({ secrets: "locked" }), "secrets.reveal")).toBeUndefined();
+        expect(orgLockRefusal(policy({ secrets: "locked" }), "secrets.set")).toMatchObject({ section: "secrets" });
+        expect(orgLockRefusal(policy({ secrets: "hidden" }), "secrets.reveal")).toMatchObject({ section: "secrets" });
+    });
+
+    it("leaves a person's own exits open whatever the policy", () => {
+        const everything = policy({ access: "hidden", agent: "hidden" });
+        expect(orgLockRefusal(everything, "DELETE /members/self")).toBeUndefined();
+        expect(orgLockRefusal(everything, "settings.confirmAiLiteracy")).toBeUndefined();
+        expect(orgLockRefusal(everything, "secrets.request")).toBeUndefined();
+    });
+
+    it("resolves a concrete request to its section through the route table", () => {
+        expect(orgSectionOfRoute(sandboxRouteFor("POST", "/members")?.name ?? "")).toBe("access");
+        expect(orgSectionOfRoute(sandboxRouteFor("DELETE", "/members/self")?.name ?? "")).toBeUndefined();
+        expect(orgSectionOfRoute(sandboxRouteFor("PUT", "/secrets/gates/OPENAI_KEY")?.name ?? "")).toBe("secrets");
+        expect(orgSectionOfRoute(sandboxRouteFor("POST", "/system/update/auto")?.name ?? "")).toBe("updates");
+    });
+
+    it("names only bound-only routes that exist and change something", () => {
+        const known = new Map([...SANDBOX_ROUTES, ...RAW_ROUTE_LIST].map((route) => [route.name, route.method]));
+        for (const name of ORG_BOUND_ROUTES) {
+            expect({ name, method: known.get(name) }).toEqual({ name, method: expect.not.stringMatching(/^(GET|HEAD)$/) });
+        }
+    });
+
+    it("refuses closing the sandbox to every browser on any bound sandbox, an all-open policy included", () => {
+        expect(orgLockRefusal(policy({}), "POST /system/access/disable")).toMatchObject({ reason: "org-locked", section: "access", org: "Urząd Gminy" });
+        expect(orgLockRefusal(policy({ access: "open" }), "POST /system/access/disable")).toMatchObject({ section: "access" });
+        expect(orgLockRefusal(undefined, "POST /system/access/disable")).toBeUndefined();
+    });
+
+    it("reads pinned preset groups it knows in the contract's order, and reports the ones it does not", () => {
+        const pinned = OrgPolicySchema.parse({ orgId: "o", orgName: "O", version: 1, preset: ["judge", "telepathy", "privacy"] });
+        expect(orgPinnedGroups(pinned)).toEqual(["privacy", "judge"]);
+        expect(orgUnknownPins(pinned)).toEqual(["telepathy"]);
+        expect(orgPinnedGroups(OrgPolicySchema.parse({ orgId: "o", orgName: "O", version: 1 }))).toEqual([]);
+        expect(orgPinnedGroups(undefined)).toEqual([]);
+    });
+
+    it("names the organisation and the items a refused pinned write would have loosened", () => {
+        expect(orgPinRefusal({ orgName: "Urząd Gminy" }, ["privacy.mode", "retention.transcriptDays"])).toEqual({
+            error: "Urząd Gminy requires privacy.mode, retention.transcriptDays to stay as it set them; ask your organisation's admin to change it",
+            reason: "org-pinned",
+            items: ["privacy.mode", "retention.transcriptDays"],
+            org: "Urząd Gminy",
+        });
+    });
+
+    it("takes the people list only as sha256 digests", () => {
+        const base = { orgId: "o", orgName: "O", version: 1, membersOnly: true };
+        expect(OrgPolicySchema.safeParse({ ...base, people: ["a".repeat(64)] }).success).toBe(true);
+        expect(OrgPolicySchema.safeParse({ ...base, people: ["clerk@gmina.test"] }).success).toBe(false);
+    });
+
+    it("reads a section a policy leaves out as open, and refuses an unknown mode", () => {
+        expect(OrgPolicySchema.parse({ orgId: "o", orgName: "O", version: 1 }).sections).toEqual({});
+        expect(OrgPolicySchema.safeParse({ orgId: "o", orgName: "O", version: 1, sections: { agent: "sealed" } }).success).toBe(false);
+    });
+});

package/src/policy/tests/reserved-servers.test.ts

@@ -25,9 +25,10 @@ describe("reserved MCP server names", () => {
 
 describe("collidesWithReservedServer", () => {
     // Derived from the manifest schema's meanings: a cli card mints a server when it serves tools, a device, a
-    // connected browser and a connected phone always do, and `mcp` is the core kind that is its own endpoint.
+    // connected browser and a connected phone always do, `mcp` is the core kind that is its own endpoint, and a `link`
+    // card is mounted as a server named after it.
     test("the minting kinds are exactly the ones whose id becomes a server name", () => {
-        expect([...MCP_SERVER_MINTING_KINDS].toSorted()).toEqual(["cli", "device", "mcp", "phone", "webext"]);
+        expect([...MCP_SERVER_MINTING_KINDS].toSorted()).toEqual(["cli", "device", "link", "mcp", "phone", "webext"]);
     });
 
     test("a kind whose id becomes a server name may not reuse a reserved one", () => {

package/src/protocol/doors/listener-protocol.ts

@@ -4,7 +4,7 @@ import { ActivityStatusSchema } from "../../schemas/activity.js";
 import { rawRouteUrl } from "../raw/raw-routes.js";
 
 // Wire between the daemon and an extension's realtime-listener gateway (ext-discord, ext-slack, ext-telegram,
-// ext-whatsapp, ext-imap, ext-google-workspace): the five /listeners/:provider routes (state, dispatch, failure,
+// ext-whatsapp, ext-imap, ext-google-workspace, ext-microsoft-365): the five /listeners/:provider routes (state, dispatch, failure,
 // status, stop). Shared here so both ends compile against one declaration.
 
 // The path of one of the five listener routes for a provider, built from RAW_ROUTES so the gateway and the daemon

package/src/protocol/doors/phone-links.ts

@@ -18,6 +18,10 @@ const PAIRING_PREFIX = "ixp1_";
 // that offers it. The code rides the fragment, which no server ever receives, so no access log holds a live pairing.
 export const PHONE_PAIR_LINK = "https://intentic.dev/phone/pair";
 
+// A watch has no camera to scan with, so its code is scanned by the phone beside it: this link opens Intentic Device on
+// that phone, which sends the code on to the watch instead of pairing itself. The code inside is the same.
+export const WATCH_PAIR_LINK = "https://intentic.dev/watch/pair";
+
 const base64url = (value: string): string => btoa(value).replaceAll("+", "-").replaceAll("/", "_").replaceAll("=", "");
 
 export const phonePairingCode = (pairing: { readonly url: string; readonly token: string }): string =>
@@ -26,12 +30,17 @@ export const phonePairingCode = (pairing: { readonly url: string; readonly token
 export const phonePairingLink = (pairing: { readonly url: string; readonly token: string }): string =>
     `${PHONE_PAIR_LINK}#${phonePairingCode(pairing)}`;
 
+export const watchPairingLink = (pairing: { readonly url: string; readonly token: string }): string =>
+    `${WATCH_PAIR_LINK}#${phonePairingCode(pairing)}`;
+
 // The phone's side, and the editor's for a pasted code; undefined for anything not one of ours. Accepts the bare code
-// or the whole link, since a person may paste either.
+// or the whole link (a phone's or a watch's), since a person may paste either.
 export const parsePhonePairingCode = (input: string): { readonly url: string; readonly token: string } | undefined => {
     const trimmed = input.trim();
     // The site serves the page with a trailing slash, so a link copied out of the browser may carry one.
-    const linked = [`${PHONE_PAIR_LINK}#`, `${PHONE_PAIR_LINK}/#`].find((prefix) => trimmed.startsWith(prefix));
+    const linked = [`${PHONE_PAIR_LINK}#`, `${PHONE_PAIR_LINK}/#`, `${WATCH_PAIR_LINK}#`, `${WATCH_PAIR_LINK}/#`].find((prefix) =>
+        trimmed.startsWith(prefix),
+    );
     const code = linked === undefined ? trimmed : trimmed.slice(linked.length);
     if (!code.startsWith(PAIRING_PREFIX)) {
         return undefined;

package/src/protocol/doors/phone-protocol.test.ts

@@ -4,7 +4,7 @@ import { packageRoot } from "@intentic/constants/node";
 import { OkSchema } from "../../schemas/shared.js";
 import { PhoneFactsSchema, PhoneScopesSchema } from "../../schemas/phone.js";
 import { PHONE_ERROR, PhoneHelloSchema, PhoneRequestSchema, PhoneResponseSchema } from "./phone-protocol.js";
-import { parsePhonePairingCode, phoneConnectUrl, phoneEnrollUrl, phonePairingCode, phonePairingLink } from "./phone-links.js";
+import { parsePhonePairingCode, phoneConnectUrl, phoneEnrollUrl, phonePairingCode, phonePairingLink, watchPairingLink } from "./phone-links.js";
 
 // The phone door's wire as examples, spelled once here: golden/phone-wire.json is this file's `wire` as JSON, and both
 // far ends test against it — the daemon's JSON-RPC link (_sandbox/sandbox/src/phones/json-rpc-link.test.ts) sends
@@ -123,6 +123,13 @@ test("a pairing round-trips as a code and as the link the QR carries", () => {
     expect(parsePhonePairingCode(phonePairingLink(pairing).replace("/pair#", "/pair/#"))).toEqual(pairing);
 });
 
+test("a watch's link carries the same code, under the path its phone hands on", () => {
+    const pairing = { url: "https://sandbox-abc.sbx.intentic.dev", token: "one-time" };
+    expect(watchPairingLink(pairing)).toBe(`https://intentic.dev/watch/pair#${phonePairingCode(pairing)}`);
+    expect(parsePhonePairingCode(watchPairingLink(pairing))).toEqual(pairing);
+    expect(parsePhonePairingCode(watchPairingLink(pairing).replace("/pair#", "/pair/#"))).toEqual(pairing);
+});
+
 test("a code that is not ours, or carries no usable url or token, is refused rather than attempted", () => {
     expect(parsePhonePairingCode("ixb1_abc")).toBeUndefined();
     expect(parsePhonePairingCode("ixp1_not-base64!")).toBeUndefined();

package/src/protocol/doors/webext-links.ts

@@ -18,6 +18,19 @@ export const webextSessionUrl = (sandboxUrl: string): string => `${sandboxUrl.re
 // an MCP result.
 export const webextLendUrl = (sandboxUrl: string): string => `${sandboxUrl.replace(/\/$/, "")}/system/webext/lend`;
 
+// Where the extension collects a stored secret it was handed a ticket to type. Its own door for the reason the two above
+// are: a tool answer over the socket lands in the model's context, and this value must never reach one.
+export const webextSecretUrl = (sandboxUrl: string): string => `${sandboxUrl.replace(/\/$/, "")}/system/webext/secret`;
+
+// The tool the daemon calls on a browser to type a secret into its focused field, taking only a ticket the daemon
+// minted for that one call. The agent's own mount of the browser never lists it (webext-peer.ts): a model holding the
+// tool would hold nothing it could use, so it is not offered.
+export const WEBEXT_TICKET_TOOL = "type_ticket";
+
+// How long a ticket waits for its browser to collect it. Both sides read it: the extension's own question to the person
+// has to be answered inside it, or the ticket it then presents has already lapsed.
+export const WEBEXT_TICKET_TTL_MS = 60_000;
+
 // One pasteable code, not two fields: base64url of {url, token}, since a popup gets one paste, not two boxes. `token`
 // is single-use and expires in ten minutes; the prefix versions the format.
 const PAIRING_PREFIX = "ixb1_";

package/src/protocol/ingress-contract.fixture.json

@@ -46,6 +46,7 @@
     ],
     "bulk": [
         "GET /diff/raw",
+        "GET /agents/{id}/documents/raw",
         "GET /workspace/raw",
         "GET /workspace/media",
         "GET /workspace/download",
@@ -61,6 +62,7 @@
     "lanes": [
         { "host": "sandbox-abcdef012345.sbx.example.test", "method": "GET", "path": "/workspace/media?path=a.mp4", "lane": "bulk" },
         { "host": "sandbox-abcdef012345.sbx.example.test", "method": "GET", "path": "/workspace/download?ticket=t", "lane": "bulk" },
+        { "host": "sandbox-abcdef012345.sbx.example.test", "method": "GET", "path": "/agents/c1/documents/raw?path=letter.odt", "lane": "bulk" },
         { "host": "sandbox-abcdef012345.sbx.example.test", "method": "POST", "path": "/workspace/upload?path=a", "lane": "bulk" },
         { "host": "sandbox-abcdef012345.sbx.example.test:443", "method": "GET", "path": "/system/runners/git/app/info/refs?service=git-upload-pack", "lane": "bulk" },
         { "host": "sandbox-abcdef012345.sbx.example.test", "method": "POST", "path": "/system/runners/git/app/git-receive-pack", "lane": "bulk" },

package/src/protocol/pairing-redeem.ts

@@ -68,7 +68,7 @@ export const redeemWhileWarming = async (
         return { kind: "answered", response };
     } catch (error) {
         if (signal?.aborted === true) {
-            // oxlint-disable-next-line typescript/only-throw-error -- the stop's own reason, as an aborted fetch rejects with it
+            // the stop's own reason, as an aborted fetch rejects with it
             throw signal.reason;
         }
         if (error instanceof Warming) {

package/src/protocol/peer-dial.test.ts

@@ -158,11 +158,11 @@ test("a far end that never answers is reported a few times, then retried quietly
     try {
         const { link, sockets, said } = dialling(60_000);
         for (let attempt = 1; attempt <= 20; attempt += 1) {
-            // oxlint-disable-next-line eslint/no-await-in-loop -- one attempt after another is the thing under test
+            // one attempt after another is the thing under test
             await waitFor(() => expect(sockets).toHaveLength(attempt));
             sockets.at(-1)?.errors();
             sockets.at(-1)?.drops(1006);
-            // oxlint-disable-next-line eslint/no-await-in-loop -- the ladder's own wait, serial by construction
+            // the ladder's own wait, serial by construction
             await advanceTimersByTimeAsync(60_000);
         }
 
@@ -197,10 +197,10 @@ test("a link that comes back is loud again about the outage after it", async ()
     try {
         const { link, sockets, said } = dialling();
         for (let attempt = 1; attempt <= 5; attempt += 1) {
-            // oxlint-disable-next-line eslint/no-await-in-loop -- one attempt after another is the thing under test
+            // one attempt after another is the thing under test
             await waitFor(() => expect(sockets).toHaveLength(attempt));
             sockets.at(-1)?.drops(1006);
-            // oxlint-disable-next-line eslint/no-await-in-loop -- the ladder's own wait, serial by construction
+            // the ladder's own wait, serial by construction
             await advanceTimersByTimeAsync(1_000);
         }
         const whileQuiet = said.length;
@@ -273,10 +273,10 @@ test("a link nobody has answered in a long time rests between tries, and is neve
         const { link, sockets, said } = dialling(RUNG_MS);
         // Up to the threshold on the ordinary ladder: drop, wait its rung, get the next socket.
         for (let attempt = 1; attempt < LONG_OUTAGE_ATTEMPTS; attempt += 1) {
-            // oxlint-disable-next-line eslint/no-await-in-loop -- one drop per attempt is serial by definition
+            // one drop per attempt is serial by definition
             await waitFor(() => expect(sockets).toHaveLength(attempt));
             sockets.at(-1)?.drops(1006);
-            // oxlint-disable-next-line eslint/no-await-in-loop -- ditto
+            // ditto
             await advanceTimersByTimeAsync(RUNG_MS);
         }
         await waitFor(() => expect(sockets).toHaveLength(LONG_OUTAGE_ATTEMPTS));

package/src/protocol/peer-mcp-server.test.ts

@@ -1,3 +1,4 @@
+import { errorMessage } from "@intentic/base/errors";
 import { z } from "zod";
 import { createMcpServer, type McpAuditEntry, textResult, tool } from "./peer-mcp-server.js";
 
@@ -32,7 +33,7 @@ const build = () => {
         ],
         noSuchTool: (name) => `This peer has no tool called "${name}".`,
         refused: (error) => error instanceof Refused,
-        errorMessage: (error) => (error instanceof Error ? error.message : String(error)),
+        errorMessage,
         audit: (entry) => void audits.push(entry),
     });
     return { handle, audits };

package/src/protocol/raw/raw-json-routes.ts

@@ -19,7 +19,7 @@ import { MemberEmailSchema, MemberGrantSchema, MemberSelfSchema, MembersListSche
 import { PhonesListSchema, PhoneWakeRegistrationSchema } from "../../schemas/phone.js";
 import { OkSchema } from "../../schemas/shared.js";
 import { EnrollCodeAnswerSchema, EnrollCodeRequestSchema, PeerPairingAnswerSchema, SyncPairAnswerSchema, SyncPairRequestSchema } from "../../schemas/short-codes.js";
-import { SpeechStatusSchema, SpeechTranscriptSchema } from "../../schemas/speech.js";
+import { SpeechStatusSchema, SpeechTranscriptSchema, SpeechWakeClaimSchema, SpeechWakeGrantSchema } from "../../schemas/speech.js";
 import {
     AuthenticationOptionsSchema,
     DaemonSessionSchema,
@@ -35,6 +35,20 @@ import {
     SessionRecoveredSchema,
 } from "../../schemas/system.js";
 import { WebExtsListSchema } from "../../schemas/webext.js";
+import {
+    InboundLinkMintedSchema,
+    InboundLinkMintSchema,
+    InboundLinksListSchema,
+    InboundLinkSummarySchema,
+    InboundLinkTermsUpdateSchema,
+    LinkAnswerSchema,
+    LinkHelloSchema,
+    LinkMessageReceiptSchema,
+    LinkMessageSchema,
+    LinkRequestDecisionSchema,
+    LinkTaskSchema,
+    LinkTaskStatusSchema,
+} from "../../schemas/links.js";
 import { UploadManifestSchema, UploadSkipSchema } from "../../schemas/workspace/workspace-upload.js";
 import {
     ArrivalAbandonedSchema,
@@ -128,6 +142,20 @@ export const RAW_JSON_ROUTES = {
     "DELETE /system/authorized-key/{machine}": { output: OkSchema },
     // Every browser session revoked, the owner's own included.
     "POST /system/sessions/revoke": { output: OkSchema },
+    // Inbound links: the roster, a mint (its token shown once), new terms, a revoke, and the owner's answer to a waiting task.
+    "GET /system/links": { output: InboundLinksListSchema },
+    "POST /system/links": { input: InboundLinkMintSchema, output: InboundLinkMintedSchema },
+    "POST /system/links/{id}": { input: InboundLinkTermsUpdateSchema, output: InboundLinkSummarySchema },
+    "DELETE /system/links/{id}": { output: OkSchema },
+    "POST /system/links/{id}/requests/{request}": { input: LinkRequestDecisionSchema, output: InboundLinkSummarySchema },
+    // The link doors, as the asking sandbox's daemon reads them. A status takes `?after=<version>&wait=<seconds>` to
+    // be held until it moves past that version.
+    "GET /link": { output: LinkHelloSchema },
+    "POST /link/conversations": { input: LinkTaskSchema, output: LinkTaskStatusSchema },
+    "GET /link/conversations/{id}": { output: LinkTaskStatusSchema },
+    "POST /link/conversations/{id}/messages": { input: LinkMessageSchema, output: LinkMessageReceiptSchema },
+    "POST /link/conversations/{id}/answer": { input: LinkAnswerSchema, output: OkSchema },
+    "POST /link/conversations/{id}/stop": { output: LinkTaskStatusSchema },
     "GET /system/control/tokens": { output: ControlTokensListSchema },
     "POST /system/control/tokens": { input: ControlTokenMintSchema, output: ControlTokenMintedSchema },
     "DELETE /system/control/tokens/{id}": { output: OkSchema },
@@ -151,6 +179,8 @@ export const RAW_JSON_ROUTES = {
     "GET /speech/status": { output: SpeechStatusSchema },
     "POST /speech/prepare": { output: SpeechStatusSchema },
     "POST /speech/transcribe": { bytes: true, output: SpeechTranscriptSchema },
+    // One device's claim on a wake word it heard, so two devices hearing the same "Leon" open one session between them.
+    "POST /speech/wake": { input: SpeechWakeClaimSchema, output: SpeechWakeGrantSchema },
     // A file written into the tree (`?path=`, the body its bytes, `x-intentic-base-hash` refusing a stale save), and the
     // pre-drop check of which dropped files are already there.
     "POST /workspace/upload": { bytes: true, output: OkSchema },