@intentic/sandbox-contract 1.344.0 → 1.346.0

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

@@ -0,0 +1,132 @@
+import { KEYRING_NAME_RE, type KeyringOrigin } from "../schemas/keyring.js";
+import {
+    type CaptureCandidate,
+    entriesFor,
+    entryNameFor,
+    findCaptureTarget,
+    gitOrigin,
+    mergeRules,
+    originKey,
+    originsOfRules,
+    rememberSwitchFor,
+    rulesForOrigin,
+    rulesServe,
+    titleForOrigin,
+} from "./keyring-origins.js";
+
+const NONE = { programs: [], packages: [], hosts: [], askpass: [] };
+
+const entry = (name: string, origin: KeyringOrigin, username?: string): CaptureCandidate => ({ name, rules: rulesForOrigin(origin), username, title: titleForOrigin(origin) });
+
+describe("origins and rules", () => {
+    test("a site keeps its host, without www and case", () => {
+        expect(rulesForOrigin({ kind: "site", host: "WWW.GitHub.com" })).toEqual({ ...NONE, hosts: ["github.com"] });
+        expect(originKey({ kind: "site", host: "www.github.com." })).toBe(originKey({ kind: "site", host: "github.com" }));
+    });
+
+    test("terminal places become askpass matchers, and read back as the same places", () => {
+        const places: KeyringOrigin[] = [
+            { kind: "ssh", target: "radar@build-01" },
+            { kind: "ssh-key", path: "/home/radar/.ssh/id_ed25519" },
+            { kind: "sudo" },
+            { kind: "sudo", user: "root" },
+        ];
+        for (const place of places) {
+            expect(originsOfRules({ ...NONE, ...rulesForOrigin(place) })).toEqual([place]);
+        }
+    });
+
+    test("git answers for every repository on its host", () => {
+        expect(gitOrigin("https://github.com/intentic/intentic.git")).toBe("https://github.com");
+        const rules = rulesForOrigin({ kind: "git", url: "https://github.com/intentic/intentic" });
+        expect(rules).toEqual({ ...NONE, askpass: ["git:https://github.com"], hosts: ["github.com"] });
+        expect(rulesServe(rules, { kind: "git", url: "https://github.com/other/repo" })).toBe(true);
+        // Its site is said once, by the git chip.
+        expect(originsOfRules(rules)).toEqual([{ kind: "git", url: "https://github.com" }]);
+    });
+
+    test("a sandbox terminal's prompt places nothing on this computer", () => {
+        expect(rulesForOrigin({ kind: "prompt", text: "Password:", command: "npm login", sandbox: "https://x.intentic.dev" })).toEqual(NONE);
+    });
+
+    test("merging adds a place without repeating one", () => {
+        const a = rulesForOrigin({ kind: "site", host: "github.com" });
+        const b = rulesForOrigin({ kind: "git", url: "https://github.com" });
+        expect(mergeRules(a, b)).toEqual({ ...NONE, hosts: ["github.com"], askpass: ["git:https://github.com"] });
+    });
+});
+
+describe("serving a place", () => {
+    test("a saved site fills its subdomains, and a wildcard its domain", () => {
+        expect(rulesServe({ ...NONE, hosts: ["github.com"] }, { kind: "site", host: "gist.github.com" })).toBe(true);
+        expect(rulesServe({ ...NONE, hosts: ["*.corp.example"] }, { kind: "site", host: "corp.example" })).toBe(true);
+        expect(rulesServe({ ...NONE, hosts: ["github.com"] }, { kind: "site", host: "notgithub.com" })).toBe(false);
+    });
+
+    test("a program matches by its file name, without case or folder", () => {
+        expect(rulesServe({ ...NONE, programs: ["C:\\Program Files\\Fortinet\\FortiClient.exe"] }, { kind: "program", program: "forticlient.EXE" })).toBe(true);
+    });
+});
+
+describe("the entry a capture updates", () => {
+    const github = entry("GITHUB_COM", { kind: "site", host: "github.com" }, "radarsu");
+    const work = entry("GITHUB_COM_WORK", { kind: "site", host: "github.com" }, "radar-work");
+
+    test("the same place and account is an update", () => {
+        expect(findCaptureTarget([github, work], { kind: "site", host: "www.github.com" }, "Radarsu")?.name).toBe("GITHUB_COM");
+    });
+
+    test("another account at the same place is a new entry", () => {
+        expect(findCaptureTarget([github], { kind: "site", host: "github.com" }, "someone-else")).toBeUndefined();
+    });
+
+    test("a sandbox prompt is found again by its title", () => {
+        const origin: KeyringOrigin = { kind: "prompt", text: "Password:", command: "npm login", sandbox: "https://x.intentic.dev" };
+        expect(findCaptureTarget([entry("NPM_LOGIN", origin)], origin, undefined)?.name).toBe("NPM_LOGIN");
+    });
+
+    test("a need offers the asked-for account first", () => {
+        expect(entriesFor([github, work], { kind: "site", host: "github.com" }, "radar-work").map((found) => found.name)).toEqual(["GITHUB_COM_WORK", "GITHUB_COM"]);
+    });
+});
+
+describe("titles and names", () => {
+    test("each place reads as a person would say it", () => {
+        expect(titleForOrigin({ kind: "site", host: "www.github.com" })).toBe("github.com");
+        expect(titleForOrigin({ kind: "program", program: "C:\\x\\FortiClient.exe" })).toBe("FortiClient");
+        expect(titleForOrigin({ kind: "program", program: "FortiClient.exe", label: "FortiClient VPN" })).toBe("FortiClient VPN");
+        expect(titleForOrigin({ kind: "ssh", target: "radar@build-01" })).toBe("ssh radar@build-01");
+        expect(titleForOrigin({ kind: "git", url: "https://github.com/a/b" })).toBe("git github.com");
+        expect(titleForOrigin({ kind: "prompt", text: "Password for npm: ", command: "npm login" })).toBe("npm login");
+        expect(titleForOrigin({ kind: "site", host: "github.com" }, "  GitHub ")).toBe("GitHub");
+    });
+
+    test("a name takes the title, then the account, then a number", () => {
+        const taken = new Set<string>();
+        const name = (title: string, user?: string): string => {
+            const made = entryNameFor(title, user, (candidate) => taken.has(candidate));
+            taken.add(made);
+            return made;
+        };
+        expect(name("github.com", "radarsu@example.com")).toBe("GITHUB_COM");
+        expect(name("github.com", "radarsu@example.com")).toBe("GITHUB_COM_RADARSU");
+        expect(name("github.com", "radarsu@example.com")).toBe("GITHUB_COM_RADARSU_2");
+        expect(name("ssh radar@build-01")).toBe("SSH_RADAR_BUILD_01");
+        expect(name("1Password")).toBe("_1PASSWORD");
+        expect(name("Zürich Bank")).toBe("ZURICH_BANK");
+        expect(name("···")).toBe("PASSWORD");
+    });
+
+    test("every name fits a reference", () => {
+        for (const title of ["a".repeat(400), "ąę", "--", "x y z", "9"]) {
+            expect(entryNameFor(title, "u", () => false)).toMatch(KEYRING_NAME_RE);
+        }
+    });
+});
+
+test("deliberate acts need no remember switch", () => {
+    expect(rememberSwitchFor("browser")).toBe("browser");
+    expect(rememberSwitchFor("git")).toBe("terminal");
+    expect(rememberSwitchFor("terminal")).toBe("sandbox");
+    expect(rememberSwitchFor("import")).toBeUndefined();
+});

package/src/policy/keyring-origins.ts

@@ -0,0 +1,287 @@
+import { KEYRING_NAME_RE, type KeyringCaptureSource, type KeyringOrigin, type KeyringRemember } from "../schemas/keyring.js";
+
+// WHERE A CREDENTIAL BELONGS, in the two shapes the product keeps it in: an ORIGIN (schemas/keyring.ts), which is how a
+// capture, an agent's need and the Passwords app speak of it ("github.com", "ssh radar@build-01"), and an entry's RULES
+// (programs, packages, hosts, askpass matchers), which is how the keyring decides where a value may go. One file maps
+// each onto the other, names and titles a new entry, and finds the entry a capture updates, so the keyring, the
+// sandbox and the app agree on all four. Pure: no crypto, no I/O, safe in a browser bundle.
+
+/** The parts of an entry's rules an origin speaks to. */
+export interface OriginRules {
+    readonly programs: readonly string[];
+    readonly packages: readonly string[];
+    readonly hosts: readonly string[];
+    readonly askpass: readonly string[];
+}
+
+const EMPTY: OriginRules = { programs: [], packages: [], hosts: [], askpass: [] };
+
+/** A host as two captures of the same site agree on it: lower case, no trailing dot, no leading `www.`. */
+export const normalizeHost = (host: string): string =>
+    host
+        .trim()
+        .toLowerCase()
+        .replace(/\.$/u, "")
+        .replace(/^www\./u, "");
+
+// A program by its executable's file name, as Windows compares them: without case, without its folder.
+const programName = (program: string): string => (program.split(/[\\/]/u).pop() ?? program).toLowerCase();
+
+const hostOfUrl = (url: string): string | undefined => {
+    try {
+        return normalizeHost(new URL(url).host);
+    } catch {
+        // allow(silent-catch): a git remote named without a scheme is not an address to take a host from
+        return undefined;
+    }
+};
+
+/** `https://github.com/org/repo` → `https://github.com`: git asks per host, and an entry answers for all its repos. */
+export const gitOrigin = (url: string): string => {
+    try {
+        const parsed = new URL(url);
+        return `${parsed.protocol}//${normalizeHost(parsed.host)}`;
+    } catch {
+        // allow(silent-catch): kept as written; it still matches itself
+        return url;
+    }
+};
+
+/** One string per place, so two captures of the same place compare equal. */
+export const originKey = (origin: KeyringOrigin): string => {
+    switch (origin.kind) {
+        case "site":
+            return `site:${normalizeHost(origin.host)}`;
+        case "program":
+            return `program:${programName(origin.program)}`;
+        case "package":
+            return `package:${origin.package}`;
+        case "ssh":
+            return `ssh:${origin.target.toLowerCase()}`;
+        case "ssh-key":
+            return `ssh-key:${origin.path}`;
+        case "sudo":
+            return `sudo:${origin.user ?? ""}`;
+        case "git":
+            return `git:${gitOrigin(origin.url)}`;
+        case "prompt":
+            return `prompt:${origin.sandbox ?? ""}:${origin.command ?? ""}:${origin.text.trim()}`;
+    }
+};
+
+/** The rules an entry needs to be used where `origin` is: what a captured credential's entry gets without anyone typing it. */
+export const rulesForOrigin = (origin: KeyringOrigin): OriginRules => {
+    switch (origin.kind) {
+        case "site":
+            return { ...EMPTY, hosts: [normalizeHost(origin.host)] };
+        case "program":
+            return { ...EMPTY, programs: [origin.program] };
+        case "package":
+            return { ...EMPTY, packages: [origin.package] };
+        case "ssh":
+            return { ...EMPTY, askpass: [`ssh:${origin.target}`] };
+        case "ssh-key":
+            return { ...EMPTY, askpass: [`ssh-key:${origin.path}`] };
+        case "sudo":
+            return { ...EMPTY, askpass: [origin.user === undefined ? "sudo" : `sudo:${origin.user}`] };
+        case "git": {
+            const host = hostOfUrl(origin.url);
+            return { ...EMPTY, askpass: [`git:${gitOrigin(origin.url)}`], hosts: host === undefined ? [] : [host] };
+        }
+        case "prompt":
+            // A sandbox terminal's prompt is no rule on this computer: the entry is found by its title, and shared on a need.
+            return origin.sandbox === undefined ? { ...EMPTY, askpass: [`prompt:${origin.text.trim()}`] } : EMPTY;
+    }
+};
+
+/** Two sets of rules as one, each list without repeats: how a second place is added to an entry. */
+export const mergeRules = (a: OriginRules, b: OriginRules): OriginRules => {
+    const union = (x: readonly string[], y: readonly string[]): string[] => [...new Set([...x, ...y])];
+    return { programs: union(a.programs, b.programs), packages: union(a.packages, b.packages), hosts: union(a.hosts, b.hosts), askpass: union(a.askpass, b.askpass) };
+};
+
+// An askpass matcher back into the origin it was made from; undefined for one this file did not make.
+const originOfMatcher = (matcher: string): KeyringOrigin | undefined => {
+    const colon = matcher.indexOf(":");
+    const head = colon === -1 ? matcher : matcher.slice(0, colon);
+    const rest = colon === -1 ? "" : matcher.slice(colon + 1);
+    switch (head) {
+        case "ssh":
+            return rest === "" ? undefined : { kind: "ssh", target: rest };
+        case "ssh-key":
+            return rest === "" ? undefined : { kind: "ssh-key", path: rest };
+        case "sudo":
+            return rest === "" ? { kind: "sudo" } : { kind: "sudo", user: rest };
+        case "git":
+            return rest === "" ? undefined : { kind: "git", url: rest };
+        case "prompt":
+            return rest === "" ? undefined : { kind: "prompt", text: rest };
+        default:
+            return undefined;
+    }
+};
+
+/** Every place an entry's rules say it is used, for the app's "Works on" chips. A `*.domain` host reads as the domain. */
+export const originsOfRules = (rules: OriginRules): KeyringOrigin[] => {
+    const fromAskpass = rules.askpass.map(originOfMatcher).filter((origin): origin is KeyringOrigin => origin !== undefined);
+    // A git entry's host is said by its `git:` matcher; listing the site again would say it twice.
+    const gitHosts = new Set(fromAskpass.flatMap((origin) => (origin.kind === "git" ? [hostOfUrl(origin.url)] : [])));
+    return [
+        ...rules.hosts.map((host) => host.replace(/^\*\./u, "")).filter((host) => !gitHosts.has(normalizeHost(host))).map((host): KeyringOrigin => ({ kind: "site", host })),
+        ...rules.programs.map((program): KeyringOrigin => ({ kind: "program", program })),
+        ...rules.packages.map((pkg): KeyringOrigin => ({ kind: "package", package: pkg })),
+        ...fromAskpass,
+    ];
+};
+
+const hostServes = (host: string, pattern: string): boolean => {
+    const want = normalizeHost(host);
+    const wildcard = pattern.startsWith("*.");
+    const base = normalizeHost(wildcard ? pattern.slice(2) : pattern);
+    // A saved `github.com` also fills `gist.github.com`, as every password manager's site matching does.
+    return want === base || want.endsWith(`.${base}`);
+};
+
+/** Whether an entry with these rules is the one for `origin`: the test a need, a fill and a capture all use. */
+export const rulesServe = (rules: OriginRules, origin: KeyringOrigin): boolean => {
+    switch (origin.kind) {
+        case "site":
+            return rules.hosts.some((pattern) => hostServes(origin.host, pattern));
+        case "program": {
+            const want = programName(origin.program);
+            return rules.programs.some((program) => programName(program) === want);
+        }
+        case "package":
+            return rules.packages.includes(origin.package);
+        case "git": {
+            const want = `git:${gitOrigin(origin.url)}`;
+            const host = hostOfUrl(origin.url);
+            return rules.askpass.some((matcher) => matcher.startsWith("git:") && `git:${gitOrigin(matcher.slice(4))}` === want) || (host !== undefined && rules.hosts.some((pattern) => hostServes(host, pattern)));
+        }
+        case "ssh":
+        case "ssh-key":
+        case "sudo":
+        case "prompt": {
+            const wanted = rulesForOrigin(origin).askpass;
+            return wanted.length > 0 && rules.askpass.some((matcher) => wanted.includes(matcher));
+        }
+    }
+};
+
+const sameUser = (a: string | undefined, b: string | undefined): boolean => (a ?? "").trim().toLowerCase() === (b ?? "").trim().toLowerCase();
+
+/** What a capture is compared against: each entry's name, the rules that place it, and the account it signs in as. */
+export interface CaptureCandidate {
+    readonly name: string;
+    readonly rules: OriginRules;
+    readonly username?: string | undefined;
+    readonly title?: string | undefined;
+}
+
+/**
+ * The entry a capture updates: one used at the same place for the same account. Undefined: the capture is a new entry,
+ * even where the place has entries for other accounts (a second GitHub login is a second entry, not an overwrite).
+ */
+export const findCaptureTarget = <T extends CaptureCandidate>(entries: readonly T[], origin: KeyringOrigin, username: string | undefined): T | undefined =>
+    entries.find((entry) => rulesServe(entry.rules, origin) && sameUser(entry.username, username)) ??
+    // A sandbox terminal's prompt places nothing on this computer, so its entry is found by the title it was given.
+    (origin.kind === "prompt" && origin.sandbox !== undefined ? entries.find((entry) => entry.title === titleForOrigin(origin) && sameUser(entry.username, username)) : undefined);
+
+/** Entries that serve `origin`, the given account first: what a need, a browser's or a phone's fill offers. */
+export const entriesFor = <T extends CaptureCandidate>(entries: readonly T[], origin: KeyringOrigin, username?: string): T[] => {
+    const serving = entries.filter((entry) => rulesServe(entry.rules, origin));
+    return username === undefined ? serving : [...serving.filter((entry) => sameUser(entry.username, username)), ...serving.filter((entry) => !sameUser(entry.username, username))];
+};
+
+const baseName = (path: string): string => path.split(/[\\/]/u).pop() ?? path;
+
+/** What a person calls the place: `github.com`, `FortiClient VPN`, `ssh radar@build-01`, `sudo`, `git github.com`. */
+export const titleForOrigin = (origin: KeyringOrigin, given?: string): string => {
+    const named = given?.trim();
+    if (named !== undefined && named !== "") {
+        return named.slice(0, 200);
+    }
+    switch (origin.kind) {
+        case "site":
+            return normalizeHost(origin.host);
+        case "program":
+            return origin.label ?? baseName(origin.program).replace(/\.exe$/iu, "");
+        case "package":
+            return origin.label ?? origin.package.split(".").pop() ?? origin.package;
+        case "ssh":
+            return `ssh ${origin.target}`;
+        case "ssh-key":
+            return `ssh key ${baseName(origin.path)}`;
+        case "sudo":
+            return origin.user === undefined ? "sudo" : `sudo as ${origin.user}`;
+        case "git":
+            return `git ${hostOfUrl(origin.url) ?? origin.url}`;
+        case "prompt":
+            return origin.command ?? origin.text.replace(/[:\s]+$/u, "");
+    }
+};
+
+const NAME_MAX = 128;
+
+// Upper case, every run of anything else one underscore, never starting with a digit: the shape a reference takes.
+const referenceName = (text: string): string => {
+    const upper = text
+        .normalize("NFKD")
+        .replace(/[\u0300-\u036f]/gu, "")
+        .toUpperCase()
+        .replace(/[^A-Z0-9]+/gu, "_")
+        .replace(/^_+|_+$/gu, "");
+    const named = upper === "" ? "PASSWORD" : /^[0-9]/u.test(upper) ? `_${upper}` : upper;
+    return named.slice(0, NAME_MAX).replace(/_+$/u, "");
+};
+
+/**
+ * A new entry's name, the `{{secret:NAME}}` an agent writes: from its title (`GITHUB_COM`), then with the account
+ * (`GITHUB_COM_RADARSU`) when that is taken, then numbered. Always matches KEYRING_NAME_RE.
+ */
+export const entryNameFor = (title: string, username: string | undefined, taken: (name: string) => boolean): string => {
+    const base = referenceName(title);
+    const tries = [base];
+    if (username !== undefined && username.trim() !== "") {
+        tries.push(referenceName(`${base}_${username.split("@")[0] ?? username}`));
+    }
+    for (const name of tries) {
+        if (!taken(name) && KEYRING_NAME_RE.test(name)) {
+            return name;
+        }
+    }
+    const stem = (tries.at(-1) ?? base).slice(0, NAME_MAX - 6);
+    for (let n = 2; ; n++) {
+        const name = `${stem}_${String(n)}`;
+        if (!taken(name)) {
+            return name;
+        }
+    }
+};
+
+/**
+ * The remember switch a capture source needs on, or undefined for a deliberate act (an import, an agent's `secrets ask`,
+ * adding by hand) that needs none.
+ */
+export const rememberSwitchFor = (source: KeyringCaptureSource): keyof KeyringRemember | undefined => {
+    switch (source) {
+        case "browser":
+            return "browser";
+        case "askpass":
+        case "git":
+            return "terminal";
+        case "app":
+            return "apps";
+        case "phone":
+            return "phone";
+        case "terminal":
+            return "sandbox";
+        case "import":
+        case "agent":
+        case "manual":
+            return undefined;
+    }
+};
+
+/** Remembering off everywhere: a vault's settings before the person's one yes. */
+export const REMEMBER_NOTHING: KeyringRemember = { browser: false, terminal: false, apps: false, phone: false, sandbox: false };

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

@@ -1,5 +1,24 @@
-import type { KeyringGrant } from "../schemas/keyring.js";
-import { grantNonce, keyFingerprint, newSealKeyPair, newSignKeyPair, seal, signGrant, unseal, verifyGrant } from "./keyring-seal.js";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { packageRoot } from "@intentic/constants/node";
+import type { KeyringGrant, SealedBox } from "../schemas/keyring.js";
+import { SealedBoxSchema } from "../schemas/keyring.js";
+import { grantNonce, keyFingerprint, newSealKeyPair, newSignKeyPair, seal, sealWithEphemeral, signGrant, unseal, verifyGrant, type SealPurpose } from "./keyring-seal.js";
+
+const goldenPath = join(packageRoot(import.meta.url), "golden", "keyring-seal.json");
+const golden = JSON.parse(readFileSync(goldenPath, "utf8")) as {
+    recipient: { publicKey: string; privateKey: string };
+    phone: { publicKey: string; privateKey: string };
+    vectors: Array<{
+        name: string;
+        plaintext: string;
+        purpose: SealPurpose;
+        ephemeral: { publicKey: string; privateKey: string };
+        iv: string;
+        box: SealedBox;
+    }>;
+    unseal: { phonePlaintext: string; phonePurpose: SealPurpose };
+};
 
 const SANDBOX = "https://a1b2c3d4e5f6.intentic.dev";
 
@@ -91,3 +110,19 @@ describe("grants", () => {
 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);
 });
+
+describe("golden vectors (shared with the Android app)", () => {
+    test.each(golden.vectors)("$name seals to the golden box", ({ name, plaintext, purpose, ephemeral, iv, box }) => {
+        const recipient = name === "phone" ? golden.phone.publicKey : golden.recipient.publicKey;
+        const rebuilt = sealWithEphemeral(recipient, plaintext, purpose, ephemeral, Buffer.from(iv, "base64url"));
+        expect(rebuilt).toEqual(SealedBoxSchema.parse(box));
+    });
+
+    test("the phone opens the golden phone box", () => {
+        const phoneVector = golden.vectors.find((vector) => vector.name === "phone");
+        if (phoneVector === undefined) {
+            throw new Error("the golden file has no phone vector");
+        }
+        expect(unseal(golden.phone, phoneVector.box, phoneVector.purpose)).toBe(golden.unseal.phonePlaintext);
+    });
+});

package/src/policy/keyring-seal.ts

@@ -51,7 +51,12 @@ export type SealPurpose =
     | { 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 };
+    | { readonly kind: "sync"; readonly account: string; readonly device: string; readonly revision: number }
+    // A credential seen in use and sent to be kept (schemas/keyring.ts KeyringCaptureItem): bound to who saw it and when,
+    // so a box lifted from one capture cannot be replayed as another's.
+    | { readonly kind: "capture"; readonly via: string; readonly at: number }
+    // A value released to a paired phone for one autofill (KeyringPhoneFill), bound to that request's nonce.
+    | { readonly kind: "phone"; readonly device: string; readonly nonce: string };
 
 export const sealAad = (purpose: SealPurpose): Buffer => {
     switch (purpose.kind) {
@@ -64,21 +69,42 @@ export const sealAad = (purpose: SealPurpose): Buffer => {
             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");
+        case "capture":
+            return Buffer.from(`capture\0${purpose.via}\0${String(purpose.at)}`, "utf8");
+        case "phone":
+            return Buffer.from(`phone\0${purpose.device}\0${purpose.nonce}`, "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, with a caller-chosen ephemeral
+// key and IV. The phone app's unit tests and golden/keyring-seal.json call this with fixed inputs so Kotlin can match.
+export const sealWithEphemeral = (
+    recipient: string,
+    plaintext: string,
+    purpose: SealPurpose,
+    ephemeralPair: KeyringKeyPair,
+    iv: Buffer,
+): SealedBox => {
+    const shared = diffieHellman({ privateKey: privateKeyOf("X25519", ephemeralPair), publicKey: publicKeyOf("X25519", recipient) });
+    const cipher = createCipheriv("aes-256-gcm", boxKey(shared, ephemeralPair.publicKey, recipient), iv);
+    cipher.setAAD(sealAad(purpose));
+    const data = Buffer.concat([cipher.update(plaintext, "utf8"), cipher.final()]);
+    return {
+        v: 1,
+        epk: ephemeralPair.publicKey,
+        iv: iv.toString("base64url"),
+        tag: cipher.getAuthTag().toString("base64url"),
+        data: data.toString("base64url"),
+    };
+};
+
 // 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") };
+    return sealWithEphemeral(recipient, plaintext, purpose, ephemeral, randomBytes(12));
 };
 
 // Opens a box sealed to `pair` for `purpose`; throws on any way of not being one (malformed, another key, another purpose).

package/src/policy/safety-policy.ts

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import { COMMAND_CLASS_LABELS, COMMAND_CLASS_PATTERNS, type CommandPattern } from "./command-classes.js";
-import { type CommandClass, CommandClassSchema, type CommandLocus, CommandLocusSchema } from "../schemas/agent.js";
+import { type CommandClass, CommandClassSchema, type CommandLocus, CommandLocusSchema } from "../schemas/command-admission.js";
 
 // The owner's safety policy as prose, judged by a model rather than a table of verdicts, since deciding whether a
 // command is malicious takes understanding a regex can't reach. Patterns (command-classes.ts) are now just triage,

package/src/policy/tests/safety-policy.test.ts

@@ -1,6 +1,6 @@
 import { COMMAND_CLASS_LABELS, COMMAND_CLASS_PATTERNS } from "../command-classes.js";
 import { COMMAND_RULE_CATALOG, DEFAULT_SAFETY_POLICY, hardRuleClasses } from "../safety-policy.js";
-import { CommandClassSchema, CommandLocusSchema } from "../../schemas/agent.js";
+import { CommandClassSchema, CommandLocusSchema } from "../../schemas/command-admission.js";
 
 // The hard rule is the one thing on this page nobody can argue with, so it's pinned here rather than trusted to review:
 // a class added silently is one an owner can never decide about for themselves.

package/src/policy/turned-away.ts

@@ -30,5 +30,20 @@ const TURNED_AWAY: ReadonlySet<string> = new Set([
     "engine-version-floor",
 ]);
 
+// The refusals about the model itself (its allowance, its account, its catalogue, its window), which another model
+// gets past: a turn one of these stops partway offers to carry on elsewhere rather than to wait.
+const ANOTHER_MODEL_CLEARS: ReadonlySet<string> = new Set([
+    "claude-not-entitled",
+    "context-window-too-small",
+    "model-helper-only",
+    "trial-unavailable",
+    "trial-model-unavailable",
+    "trial-exhausted",
+    "model-unavailable",
+]);
+
+/** Whether another model would get past a refusal: the trial's, the model's, or the account's on it. */
+export const anotherModelClears = (code: string | undefined): boolean => code !== undefined && ANOTHER_MODEL_CLEARS.has(code);
+
 /** Whether a failure code refuses a turn before the model sees any of it. */
 export const turnedAwayCode = (code: string | undefined): boolean => code !== undefined && TURNED_AWAY.has(code);

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

@@ -19,3 +19,6 @@ export type HostHello = z.infer<typeof HostHelloSchema>;
 // The URL the machine's agent dials, given the sandbox's public URL. Carries no credential (the token rides the hello
 // frame); one place builds it, so the agent and the daemon route can't disagree.
 export const hostConnectUrl = (sandboxUrl: string): string => `${sandboxUrl.replace(/^http/, "ws").replace(/\/$/, "")}/system/hosts/connect`;
+
+// Where a connected machine tells its sandbox that Passwords shares changed (2026-10-20), bearer-authenticated.
+export const hostKeyringChangedUrl = (sandboxUrl: string): string => `${sandboxUrl.replace(/\/$/, "")}/system/hosts/keyring-changed`;

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

@@ -24,6 +24,9 @@ export const RunnerHelloSchema = z.object({
     // tag names its own container (`intentic-sandbox-env-<slug>:<hash>`), so two sides on one base and one overlay
     // never share it. Absent on an old image, which is then compared by `image` alone.
     baseImage: z.string().optional(),
+    // That base's registry digest (SANDBOX_BASE_DIGEST), when the runner's machine could read one; parity then compares
+    // the exact image rather than a tag two machines may have pulled at different moments (state/sandbox-build.ts).
+    baseDigest: z.string().optional(),
     channel: z.string().optional(),
     overlayHash: z.string().optional(),
     // Runner's declared settings-only sandbox.toml (definition.ts), diffed against the parent's to itemize drift;
@@ -147,7 +150,7 @@ export const RunnerSummarySchema = z.object({
     overlayHash: z.string().optional(),
     facts: RunnerFactsSchema.optional(),
     lastSeen: z.number().optional(),
-    // Computed once by the daemon (runners/runner-parity.ts), so every surface shows the same badge.
+    // Computed once by the daemon (buildParity, state/sandbox-build.ts), so every surface shows the same badge.
     parity: RunnerParitySchema,
     // Where the runner's environment differs from this sandbox's, one line per difference; absent if never reported,
     // empty if they agree. A Setting line is fixable live; an overlay line needs a rebuild.

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

@@ -22,6 +22,9 @@ export const webextLendUrl = (sandboxUrl: string): string => `${sandboxUrl.repla
 // 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`;
 
+// Where the extension tells its sandbox that site access changed outside the popup (2026-10-20), bearer-authenticated.
+export const webextGrantsChangedUrl = (sandboxUrl: string): string => `${sandboxUrl.replace(/\/$/, "")}/system/webext/grants-changed`;
+
 // 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.