@intentic/sandbox-contract 1.337.0 → 1.338.0

package/src/policy/keyring-seal.test.ts

@@ -0,0 +1,93 @@
+import type { KeyringGrant } from "../schemas/keyring.js";
+import { grantNonce, keyFingerprint, newSealKeyPair, newSignKeyPair, seal, signGrant, unseal, verifyGrant } from "./keyring-seal.js";
+
+const SANDBOX = "https://a1b2c3d4e5f6.intentic.dev";
+
+const grantAt = (now: number, over: Partial<KeyringGrant> = {}): KeyringGrant => ({
+    v: 1,
+    sandbox: SANDBOX,
+    secret: "VPN_FORTI",
+    target: { kind: "window", programs: ["FortiClient.exe"], anyField: false },
+    purpose: "agent",
+    detail: "FortiClient sign-in",
+    nonce: grantNonce(),
+    issuedAt: now,
+    expiresAt: now + 60_000,
+    ...over,
+});
+
+describe("sealed boxes", () => {
+    test("open for their own key and purpose", () => {
+        const pair = newSealKeyPair();
+        const purpose = { kind: "release", sandbox: SANDBOX, secret: "VPN_FORTI", nonce: grantNonce() } as const;
+        const box = seal(pair.publicKey, "hunter2-but-longer", purpose);
+        expect(unseal(pair, box, purpose)).toBe("hunter2-but-longer");
+    });
+
+    test("refuse another key", () => {
+        const purpose = { kind: "inbox", sandbox: SANDBOX, secret: "X" } as const;
+        const box = seal(newSealKeyPair().publicKey, "value", purpose);
+        expect(() => unseal(newSealKeyPair(), box, purpose)).toThrow();
+    });
+
+    test("refuse another purpose, so one release cannot stand in for another", () => {
+        const pair = newSealKeyPair();
+        const nonce = grantNonce();
+        const box = seal(pair.publicKey, "value", { kind: "release", sandbox: SANDBOX, secret: "A", nonce });
+        expect(() => unseal(pair, box, { kind: "release", sandbox: SANDBOX, secret: "B", nonce })).toThrow();
+        expect(() => unseal(pair, box, { kind: "type", sandbox: SANDBOX, secret: "A", nonce })).toThrow();
+    });
+
+    test("are fresh every time, so equal values do not look equal", () => {
+        const pair = newSealKeyPair();
+        const purpose = { kind: "inbox", sandbox: SANDBOX, secret: "X" } as const;
+        expect(seal(pair.publicKey, "same", purpose).data).not.toBe(seal(pair.publicKey, "same", purpose).data);
+    });
+});
+
+describe("grants", () => {
+    test("verify under the signing key", () => {
+        const pair = newSignKeyPair();
+        const now = Date.now();
+        const verdict = verifyGrant(pair.publicKey, signGrant(pair, grantAt(now)), now + 1000);
+        expect(verdict.ok).toBe(true);
+        expect(verdict.ok && verdict.grant.secret).toBe("VPN_FORTI");
+    });
+
+    test("refuse another sandbox's key", () => {
+        const now = Date.now();
+        const verdict = verifyGrant(newSignKeyPair().publicKey, signGrant(newSignKeyPair(), grantAt(now)), now);
+        expect(verdict).toMatchObject({ ok: false, code: "bad-grant" });
+    });
+
+    test("refuse a payload changed after signing", () => {
+        const pair = newSignKeyPair();
+        const now = Date.now();
+        const signed = signGrant(pair, grantAt(now));
+        // SAFETY: the payload is the grant signGrant just serialised, so it parses back to one.
+        const body = JSON.parse(Buffer.from(signed.payload, "base64url").toString("utf8")) as KeyringGrant;
+        const changed = Buffer.from(JSON.stringify({ ...body, secret: "BANK" }), "utf8").toString("base64url");
+        expect(verifyGrant(pair.publicKey, { ...signed, payload: changed }, now)).toMatchObject({ ok: false, code: "bad-grant" });
+    });
+
+    test("expire", () => {
+        const pair = newSignKeyPair();
+        const now = Date.now();
+        expect(verifyGrant(pair.publicKey, signGrant(pair, grantAt(now)), now + 61_000)).toMatchObject({ ok: false, code: "expired" });
+    });
+
+    test("are never signed for longer than two minutes", () => {
+        const now = Date.now();
+        expect(() => signGrant(newSignKeyPair(), grantAt(now, { expiresAt: now + 5 * 60_000 }))).toThrow();
+    });
+
+    test("from far in the future are not this sandbox's", () => {
+        const pair = newSignKeyPair();
+        const now = Date.now();
+        expect(verifyGrant(pair.publicKey, signGrant(pair, grantAt(now + 10 * 60_000)), now)).toMatchObject({ ok: false, code: "bad-grant" });
+    });
+});
+
+test("fingerprints read in groups of four", () => {
+    expect(keyFingerprint(newSealKeyPair().publicKey)).toMatch(/^[0-9A-F]{4}-[0-9A-F]{4}-[0-9A-F]{4}-[0-9A-F]{4}$/u);
+});

package/src/policy/keyring-seal.ts

@@ -0,0 +1,148 @@
+import { createCipheriv, createDecipheriv, createPrivateKey, createPublicKey, diffieHellman, generateKeyPairSync, hkdfSync, randomBytes, sign, verify, type KeyObject } from "node:crypto";
+import { z } from "zod";
+import {
+    KEYRING_GRANT_TTL_MAX_MS,
+    KEYRING_KEY_RE,
+    KeyringGrantSchema,
+    type KeyringGrant,
+    type SealedBox,
+    SealedBoxSchema,
+    type SignedKeyringGrant,
+} from "../schemas/keyring.js";
+
+// The two primitives a device-held secret rides on (schemas/keyring.ts): a SEALED BOX, a value only the holder of one
+// X25519 key can open, and a GRANT, the sandbox's Ed25519-signed word for one use of one value. Shared by the daemon,
+// which signs grants and opens what is sealed to it, and the keyring, which verifies grants and seals; one file so the
+// two cannot drift on an encoding.
+
+const SEAL_INFO = Buffer.from("intentic-keyring/seal/v1", "utf8");
+const GRANT_DOMAIN = Buffer.from("intentic-keyring/grant/v1\0", "utf8");
+// A clock on either side may run a little ahead; a grant from much further in the future is not one this sandbox made.
+const GRANT_SKEW_MS = 30_000;
+
+// A key pair as it is stored: both halves raw, base64url, the `x` and `d` of their JWK.
+export interface KeyringKeyPair {
+    readonly publicKey: string;
+    readonly privateKey: string;
+}
+
+type Curve = "X25519" | "Ed25519";
+
+// The halves of an OKP key's JWK, which Node always writes for a private key it just made.
+const OkpJwkSchema = z.object({ x: z.string().regex(KEYRING_KEY_RE), d: z.string().regex(KEYRING_KEY_RE) });
+
+const pairOf = (curve: Curve): KeyringKeyPair => {
+    const { privateKey } = curve === "X25519" ? generateKeyPairSync("x25519") : generateKeyPairSync("ed25519");
+    const jwk = OkpJwkSchema.parse(privateKey.export({ format: "jwk" }));
+    return { publicKey: jwk.x, privateKey: jwk.d };
+};
+
+export const newSealKeyPair = (): KeyringKeyPair => pairOf("X25519");
+export const newSignKeyPair = (): KeyringKeyPair => pairOf("Ed25519");
+
+const publicKeyOf = (curve: Curve, x: string): KeyObject => createPublicKey({ key: { kty: "OKP", crv: curve, x }, format: "jwk" });
+const privateKeyOf = (curve: Curve, pair: KeyringKeyPair): KeyObject =>
+    createPrivateKey({ key: { kty: "OKP", crv: curve, x: pair.publicKey, d: pair.privateKey }, format: "jwk" });
+
+// What a box is sealed FOR, mixed into its authentication tag: a box opened under any other purpose fails, so a value
+// released for one grant cannot be presented as another's, nor a typing payload as an inbox item.
+export type SealPurpose =
+    | { readonly kind: "release"; readonly sandbox: string; readonly secret: string; readonly nonce: string }
+    | { readonly kind: "type"; readonly sandbox: string; readonly secret: string; readonly nonce: string }
+    | { readonly kind: "inbox"; readonly sandbox: string; readonly secret: string }
+    | { readonly kind: "copy"; readonly sandbox: string; readonly secret: string; readonly updatedAt: number }
+    | { readonly kind: "sync"; readonly account: string; readonly device: string; readonly revision: number };
+
+export const sealAad = (purpose: SealPurpose): Buffer => {
+    switch (purpose.kind) {
+        case "release":
+        case "type":
+            return Buffer.from(`${purpose.kind}\0${purpose.sandbox}\0${purpose.secret}\0${purpose.nonce}`, "utf8");
+        case "inbox":
+            return Buffer.from(`inbox\0${purpose.sandbox}\0${purpose.secret}`, "utf8");
+        case "copy":
+            return Buffer.from(`copy\0${purpose.sandbox}\0${purpose.secret}\0${String(purpose.updatedAt)}`, "utf8");
+        case "sync":
+            return Buffer.from(`sync\0${purpose.account}\0${purpose.device}\0${String(purpose.revision)}`, "utf8");
+    }
+};
+
+const boxKey = (shared: Buffer, epk: string, recipient: string): Buffer =>
+    Buffer.from(hkdfSync("sha256", shared, Buffer.concat([Buffer.from(epk, "base64url"), Buffer.from(recipient, "base64url")]), SEAL_INFO, 32));
+
+// Seals `plaintext` to the holder of `recipient`'s private half, for `purpose` alone.
+export const seal = (recipient: string, plaintext: string, purpose: SealPurpose): SealedBox => {
+    const ephemeral = newSealKeyPair();
+    const shared = diffieHellman({ privateKey: privateKeyOf("X25519", ephemeral), publicKey: publicKeyOf("X25519", recipient) });
+    const iv = randomBytes(12);
+    const cipher = createCipheriv("aes-256-gcm", boxKey(shared, ephemeral.publicKey, recipient), iv);
+    cipher.setAAD(sealAad(purpose));
+    const data = Buffer.concat([cipher.update(plaintext, "utf8"), cipher.final()]);
+    return { v: 1, epk: ephemeral.publicKey, iv: iv.toString("base64url"), tag: cipher.getAuthTag().toString("base64url"), data: data.toString("base64url") };
+};
+
+// Opens a box sealed to `pair` for `purpose`; throws on any way of not being one (malformed, another key, another purpose).
+export const unseal = (pair: KeyringKeyPair, box: SealedBox, purpose: SealPurpose): string => {
+    const parsed = SealedBoxSchema.parse(box);
+    const shared = diffieHellman({ privateKey: privateKeyOf("X25519", pair), publicKey: publicKeyOf("X25519", parsed.epk) });
+    const decipher = createDecipheriv("aes-256-gcm", boxKey(shared, parsed.epk, pair.publicKey), Buffer.from(parsed.iv, "base64url"));
+    decipher.setAAD(sealAad(purpose));
+    decipher.setAuthTag(Buffer.from(parsed.tag, "base64url"));
+    return Buffer.concat([decipher.update(Buffer.from(parsed.data, "base64url")), decipher.final()]).toString("utf8");
+};
+
+// A fresh grant's nonce: 16 random bytes, base64url.
+export const grantNonce = (): string => randomBytes(16).toString("base64url");
+
+export const signGrant = (pair: KeyringKeyPair, grant: KeyringGrant): SignedKeyringGrant => {
+    const body = KeyringGrantSchema.parse(grant);
+    if (body.expiresAt - body.issuedAt > KEYRING_GRANT_TTL_MAX_MS || body.expiresAt <= body.issuedAt) {
+        throw new Error(`a keyring grant lives at most ${String(KEYRING_GRANT_TTL_MAX_MS / 1000)} s`);
+    }
+    const payload = Buffer.from(JSON.stringify(body), "utf8");
+    const sig = sign(null, Buffer.concat([GRANT_DOMAIN, payload]), privateKeyOf("Ed25519", pair));
+    return { payload: payload.toString("base64url"), sig: sig.toString("base64url") };
+};
+
+export type GrantVerdict =
+    | { readonly ok: true; readonly grant: KeyringGrant }
+    | { readonly ok: false; readonly code: "bad-grant" | "expired"; readonly reason: string };
+
+// Verifies `signed` against the sandbox's pinned signing key at `nowMs`. The keyring checks the nonce, the share and
+// the target against its own facts; this says only whether the sandbox said it, and said it recently.
+export const verifyGrant = (signKey: string, signed: SignedKeyringGrant, nowMs: number): GrantVerdict => {
+    let payload: Buffer;
+    try {
+        payload = Buffer.from(signed.payload, "base64url");
+        if (!verify(null, Buffer.concat([GRANT_DOMAIN, payload]), publicKeyOf("Ed25519", signKey), Buffer.from(signed.sig, "base64url"))) {
+            return { ok: false, code: "bad-grant", reason: "the grant's signature is not the sandbox's" };
+        }
+    } catch {
+        return { ok: false, code: "bad-grant", reason: "the grant could not be read" };
+    }
+    let parsed: unknown;
+    try {
+        parsed = JSON.parse(payload.toString("utf8"));
+    } catch {
+        return { ok: false, code: "bad-grant", reason: "the grant is not JSON" };
+    }
+    const grant = KeyringGrantSchema.safeParse(parsed);
+    if (!grant.success) {
+        return { ok: false, code: "bad-grant", reason: "the grant is not one this keyring knows how to read" };
+    }
+    const { issuedAt, expiresAt } = grant.data;
+    if (expiresAt - issuedAt > KEYRING_GRANT_TTL_MAX_MS || expiresAt <= issuedAt || issuedAt > nowMs + GRANT_SKEW_MS) {
+        return { ok: false, code: "bad-grant", reason: "the grant's times are not ones this sandbox would sign" };
+    }
+    if (expiresAt <= nowMs) {
+        return { ok: false, code: "expired", reason: "the grant has expired: the sandbox asks again" };
+    }
+    return { ok: true, grant: grant.data };
+};
+
+// A short, readable fingerprint of a public key, for a person comparing what two screens show.
+export const keyFingerprint = (key: string): string => {
+    const raw = Buffer.from(key, "base64url");
+    const hex = raw.subarray(0, 8).toString("hex").toUpperCase();
+    return hex.replace(/(.{4})(?=.)/gu, "$1-");
+};

package/src/policy/message-limits.ts

@@ -5,6 +5,7 @@
 export const MESSAGE_LIMITS = {
     bluesky: 300,
     discord: 2_000,
+    facebook: 63_206,
     instagram: 2_200,
     linkedin: 3_000,
     mastodon: 500,
@@ -12,6 +13,8 @@ export const MESSAGE_LIMITS = {
     slack: 4_000,
     // sendMessage refuses anything longer outright.
     telegram: 4_096,
+    // A video's caption; a comment under one stops at 150.
+    tiktok: 4_000,
     // A linked device (what the WhatsApp extension is) sends up to 65,536; the 4,096 often quoted is the Business API's.
     whatsapp: 65_536,
     x: 280,

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/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/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) {