@intentic/sandbox-contract 1.331.0 → 1.333.0

package/src/policy/device-programs.ts

@@ -0,0 +1,137 @@
+import { z } from "zod";
+
+// WHICH DEVICE TOOLS CARRY A PROGRAM (2026-10-12). A command on somebody's own computer arrives by more doors than
+// `run_command`: `app_start` starts a program with arguments, `open` starts whatever its target names (on Linux a
+// target with spaces is split into a program and arguments and spawned), `android_shell` hands a line to a phone's
+// shell, and the input tools put text where a terminal could run it. The daemon's gate used to know two of those by
+// name, the machine's own checks a different few, and `app_start program=powershell args=[…]` slipped past the judge, the
+// card and the unattended refusal. This is the one table both ends read: the tool, and how to lift the command line
+// out of its arguments. A device tool that carries a program is added here, or the machine's test says it is missing.
+
+/**
+ * What a call's program is, which decides how it is read:
+ * - `command`: a command line for the machine's own shell, or a program started with arguments; judged as `run_command`.
+ * - `phone-command`: a line for an attached phone's shell, judged as the `adb shell` program the machine runs for it.
+ * - `app-launch`: an application, URL or document started with nothing to interpret; the ordinary GUI launch, low risk.
+ * - `typed`: text put where a terminal could run it (typed, pasted, set into a field).
+ */
+export type ProgramKind = "command" | "phone-command" | "app-launch" | "typed";
+
+/** The program a tool call carries, as the classifier and the judge read it. */
+export interface ProgramReading {
+    readonly tool: string;
+    readonly kind: ProgramKind;
+    /** The command line as a shell would read it. */
+    readonly commandLine: string;
+}
+
+// The fields of every tool in the table below. One that is the wrong type reads as absent rather than failing the
+// parse: such a call never runs, since the device checks its input against its own schema before anything else.
+export const ProgramArgumentsSchema = z.looseObject({
+    command: z.string().optional().catch(undefined),
+    serial: z.string().optional().catch(undefined),
+    program: z.string().optional().catch(undefined),
+    args: z.array(z.string()).optional().catch(undefined),
+    target: z.string().optional().catch(undefined),
+    action: z.string().optional().catch(undefined),
+    text: z.string().optional().catch(undefined),
+    value: z.string().optional().catch(undefined),
+});
+export type ProgramArguments = z.infer<typeof ProgramArgumentsSchema>;
+
+interface ProgramCarrier {
+    readonly tool: string;
+    /** In words: where the program is in the arguments. */
+    readonly carries: string;
+    readonly read: (args: ProgramArguments) => Omit<ProgramReading, "tool"> | undefined;
+}
+
+const present = (value: string | undefined): string | undefined => (value === undefined || value.trim() === "" ? undefined : value);
+
+// A program by the name it is known by (`rm`, `powershell`), not the path or the `.exe` it was started through.
+const programName = (program: string): string => (program.split(/[/\\]/).at(-1) ?? program).replace(/\.exe$/i, "");
+
+/**
+ * The program and its arguments as the one command line they amount to: the program by its name, each argument quoted
+ * only where a shell would need it, so the line reads the way a person would type it.
+ */
+export const commandLineOf = (program: string, args: readonly string[]): string =>
+    [
+        programName(program),
+        ...args.map((arg) => (arg === "" || /[\s'"|;&<>()$`\\]/.test(arg) ? (arg.includes("'") ? `"${arg}"` : `'${arg}'`) : arg)),
+    ].join(" ");
+
+// A phone's serial as adb prints one (a USB serial, `ip:port`, an mDNS name), and nothing else: a serial is spliced into
+// the program judged below, where a `#` or a quote in it could make the command after it read as inert.
+const ADB_SERIAL = /^[\w.:-]+$/;
+
+// A URL, or `www.`/`mailto:` which the machine opens the same way (desktop-automation's looksLikeUrl).
+const URL_TARGET = /^(?:[a-z][a-z0-9+.-]*:\/\/|www\.|mailto:)/i;
+
+const typedBy = (tool: string, action: string, field: "text" | "value"): ProgramCarrier => ({
+    tool,
+    carries: `${field}, when action is ${action}`,
+    read: (args) => {
+        const typed = args.action === action ? present(args[field]) : undefined;
+        return typed === undefined ? undefined : { kind: "typed", commandLine: typed };
+    },
+});
+
+/** Every device tool that carries a program. */
+export const DEVICE_PROGRAM_TOOLS: readonly ProgramCarrier[] = [
+    {
+        tool: "run_command",
+        carries: "command",
+        read: ({ command }) => {
+            const line = present(command);
+            return line === undefined ? undefined : { kind: "command", commandLine: line };
+        },
+    },
+    {
+        tool: "android_shell",
+        carries: "command, run as `adb [-s serial] shell <command>`",
+        read: ({ command, serial }) => {
+            const line = present(command);
+            if (line === undefined) {
+                return undefined;
+            }
+            return { kind: "phone-command", commandLine: `adb ${serial !== undefined && ADB_SERIAL.test(serial) ? `-s ${serial} ` : ""}shell ${line}` };
+        },
+    },
+    {
+        tool: "app_start",
+        carries: "program and args",
+        read: ({ program, args }) => {
+            const started = present(program);
+            if (started === undefined) {
+                return undefined;
+            }
+            // With nothing to interpret it is a launch; with arguments it is a command by another door, whatever the
+            // program is: `rm -rf ~`, `curl … | sh` and `powershell -c …` read the same here as in run_command.
+            return { kind: args === undefined || args.length === 0 ? "app-launch" : "command", commandLine: commandLineOf(started, args ?? []) };
+        },
+    },
+    {
+        tool: "open",
+        carries: "target",
+        read: ({ target }) => {
+            const opened = present(target);
+            if (opened === undefined) {
+                return undefined;
+            }
+            // A URL or a single word (an application name, a file path) is opened. A target with spaces that is not a URL
+            // can be split into a program and arguments and spawned, so it is read as the command it may be.
+            return { kind: URL_TARGET.test(opened) || !/\s/.test(opened.trim()) ? "app-launch" : "command", commandLine: opened };
+        },
+    },
+    typedBy("device", "type", "text"),
+    typedBy("android_act", "type", "text"),
+    typedBy("clipboard", "write", "text"),
+    typedBy("ui_act", "set_value", "value"),
+];
+
+/** The program a `tools/call` of `tool` carries, or undefined for a tool that carries none or a call with nothing in the place the table looks. */
+export const programInCall = (tool: string, args: ProgramArguments): ProgramReading | undefined => {
+    const read = DEVICE_PROGRAM_TOOLS.find((carrier) => carrier.tool === tool)?.read(args);
+    return read === undefined ? undefined : { tool, ...read };
+};

package/src/policy/identity-assertion.ts

@@ -0,0 +1,130 @@
+import { createPrivateKey, createPublicKey, randomBytes, sign as edSign, verify as edVerify } from "node:crypto";
+import { z } from "zod";
+import { SANDBOX_ID } from "../ids/tunnel-ids.js";
+
+// The platform's signed word that a signed-in person controls an email address, spent on one sandbox's daemon. It is how
+// an address no identity provider vouches for (a custom domain on Fastmail, Proton, a company's own mail server) reaches
+// a sandbox: the platform confirmed the address by mailing it a code, and nobody else could. The daemon accepts it only
+// where its owner opted in for that person (the owner record or the member row says `emailSignIn`), and on hosted
+// machines, where the platform already holds the machine. Signed with a key of its own (IDENTITY_SIGNING_KEY), never the
+// ingress key, so neither credential can stand in for the other.
+
+const ASSERTION_PREFIX = "pa1";
+
+// One round trip to the daemon and a retry; a lifted assertion is dead before anyone reads the log it sat in.
+export const IDENTITY_ASSERTION_TTL_MS = 2 * 60_000;
+// The longest life a daemon accepts whatever the claim says, so a platform minting with a wrong clock or a wrong ttl
+// still cannot hand out a credential that outlives a replay window the daemon can hold in memory.
+export const IDENTITY_ASSERTION_MAX_TTL_MS = 5 * 60_000;
+
+// The env var that carries the platform's identity key on a hosted machine, which boots before its first announce. A
+// sandbox on its owner's own machine learns the same key from the announce answer (`AnnounceAcceptedSchema`).
+export const ENV_PLATFORM_IDENTITY_KEY = "PLATFORM_IDENTITY_KEY";
+
+// How the platform confirmed the address it vouches for: a code it mailed, or a Google sign-in it verified.
+export const IdentityAssertionMethodSchema = z.enum(["email", "google"]);
+export type IdentityAssertionMethod = z.infer<typeof IdentityAssertionMethodSchema>;
+
+// The signed claim, times in seconds like the owner ticket's. `nonce` is unique per mint: the daemon spends each once.
+export interface IdentityAssertion {
+    readonly sandboxId: string;
+    readonly email: string;
+    readonly method: IdentityAssertionMethod;
+    readonly issuedAt: number;
+    readonly expiresAt: number;
+    readonly nonce: string;
+}
+
+const base64url = (bytes: Buffer): string => bytes.toString("base64url");
+
+// The prefix is part of what is signed, so an assertion is never a valid signature over anything else the same key
+// might one day sign, and an owner ticket or a grant (which sign their bare payload) is never an assertion.
+const signedBytes = (payload: Buffer): Buffer => Buffer.concat([Buffer.from(`${ASSERTION_PREFIX}.`, "utf8"), payload]);
+
+export const isIdentityAssertion = (bearer: string): boolean => bearer.startsWith(`${ASSERTION_PREFIX}.`);
+
+export const mintIdentityAssertion = (
+    privateKeyPem: string,
+    claim: {
+        readonly sandboxId: string;
+        readonly email: string;
+        readonly method: IdentityAssertionMethod;
+        readonly issuedAtMs: number;
+        readonly ttlMs?: number;
+    },
+): string => {
+    if (!SANDBOX_ID.test(claim.sandboxId)) {
+        throw new Error(`an identity assertion names a 12-hex sandbox id, got "${claim.sandboxId}"`);
+    }
+    if (claim.email.trim() === "") {
+        throw new Error("an identity assertion names an address");
+    }
+    const ttlMs = claim.ttlMs ?? IDENTITY_ASSERTION_TTL_MS;
+    if (ttlMs <= 0 || ttlMs > IDENTITY_ASSERTION_MAX_TTL_MS) {
+        throw new Error(`an identity assertion lives at most ${IDENTITY_ASSERTION_MAX_TTL_MS} ms`);
+    }
+    const iat = Math.floor(claim.issuedAtMs / 1000);
+    const exp = Math.floor((claim.issuedAtMs + ttlMs) / 1000);
+    const payload = Buffer.from(
+        JSON.stringify({
+            v: 1,
+            sub: claim.sandboxId,
+            email: claim.email.trim().toLowerCase(),
+            amr: claim.method,
+            iat,
+            exp,
+            jti: base64url(randomBytes(16)),
+        }),
+        "utf8",
+    );
+    const signature = edSign(null, signedBytes(payload), createPrivateKey(privateKeyPem));
+    return `${ASSERTION_PREFIX}.${base64url(payload)}.${base64url(signature)}`;
+};
+
+// What the signed payload must be, read only after the signature checked out.
+const AssertionPayloadSchema = z.object({
+    v: z.literal(1),
+    sub: z.string().regex(SANDBOX_ID),
+    email: z.string().min(1),
+    amr: IdentityAssertionMethodSchema,
+    iat: z.number(),
+    exp: z.number(),
+    jti: z.string().min(16),
+});
+
+const parsePayload = (payload: Buffer): z.infer<typeof AssertionPayloadSchema> | undefined => {
+    try {
+        return AssertionPayloadSchema.safeParse(JSON.parse(payload.toString("utf8"))).data;
+    } catch {
+        // allow(silent-catch): a payload that is not JSON is an invalid assertion, which undefined is how this says.
+        return undefined;
+    }
+};
+
+// Verifies an assertion against the platform's public key at nowMs; undefined for any way of being invalid (wrong
+// prefix, bad signature, malformed claim, expired, issued in the future, living longer than the daemon allows). The
+// caller checks sandboxId against its own id and spends the nonce.
+export const verifyIdentityAssertion = (publicKeyPem: string, token: string, nowMs: number): IdentityAssertion | undefined => {
+    const [prefix, encodedPayload, encodedSignature, ...rest] = token.split(".");
+    if (prefix !== ASSERTION_PREFIX || encodedPayload === undefined || encodedSignature === undefined || rest.length > 0) {
+        return undefined;
+    }
+    const payload = Buffer.from(encodedPayload, "base64url");
+    try {
+        if (!edVerify(null, signedBytes(payload), createPublicKey(publicKeyPem), Buffer.from(encodedSignature, "base64url"))) {
+            return undefined;
+        }
+    } catch {
+        // allow(silent-catch): a key or signature that does not parse verifies nothing: the assertion is invalid, said as undefined.
+        return undefined;
+    }
+    const claim = parsePayload(payload);
+    if (claim === undefined) {
+        return undefined;
+    }
+    // A minute of clock skew either way, as the daemon allows Google's tokens; never a claim from further ahead.
+    if (claim.exp * 1000 <= nowMs || claim.iat * 1000 > nowMs + 60_000 || (claim.exp - claim.iat) * 1000 > IDENTITY_ASSERTION_MAX_TTL_MS) {
+        return undefined;
+    }
+    return { sandboxId: claim.sub, email: claim.email, method: claim.amr, issuedAt: claim.iat, expiresAt: claim.exp, nonce: claim.jti };
+};

package/src/policy/sandbox-power.ts

@@ -0,0 +1,247 @@
+import { inertRegions, isLive } from "../text/shell-regions.js";
+import type { CommandSpan } from "./command-classes.js";
+
+// A SHELL COMMAND THAT STARTS, STOPS OR REPLACES A SANDBOX CONTAINER (2026-10-12). `ic sandbox restart work` and
+// `docker stop intentic-sandbox-work` end the same turns the device tools manage_sandbox and swap_sandbox end, but they
+// arrive as text in run_command, where no tool name says what they are. This reads that text once, for both ends that
+// have to answer it: the daemon, which asks the owner before an agent cuts the sandbox it runs in while others are
+// working (hosts/host-restart-guard.ts), and the device agent, whose "Manage sandboxes" switch decides whether anything
+// may do this at all (the machine's tools/shell.ts). The same verbs and the same wording, so a command and the tool
+// that does the same job cannot drift apart.
+
+/** The sandbox operations a command can name, in the words `ic sandbox` spells them. */
+export type SandboxPowerOp =
+    | "start"
+    | "stop"
+    | "restart"
+    | "sleep"
+    | "remove"
+    | "update"
+    | "prepare"
+    | "rebuild"
+    | "rollback"
+    | "dev"
+    | "resize"
+    | "restore"
+    | "connect";
+
+/** The owner's own word for an operation, as a card or a refusal says it ("<doing> this sandbox now?"). */
+export const SANDBOX_POWER_DOING = {
+    start: "Start",
+    stop: "Stop",
+    restart: "Restart",
+    sleep: "Stop",
+    remove: "Remove",
+    update: "Update",
+    prepare: "Prepare an update for",
+    rebuild: "Rebuild",
+    rollback: "Roll back",
+    dev: "Update",
+    resize: "Restart with new resources",
+    restore: "Restore a backup over",
+    connect: "Reinstall",
+} as const satisfies Record<SandboxPowerOp, string>;
+
+/** One command that manages a sandbox container, and what it aims at. */
+export interface SandboxPowerCommand {
+    readonly via: "ic" | "docker";
+    readonly op: SandboxPowerOp;
+    /** Whether it ends the turns of a sandbox that is running; false for a start, a download, a resource ask saved for later. */
+    readonly stops: boolean;
+    /** The slugs (`ic`) or container names (`docker`) it names, as written; an expansion (`$x`, `$(…)`, `*`) stays as typed. */
+    readonly targets: readonly string[];
+    /** Names none: `ic sandbox restart` alone (the only sandbox the device runs), `remove --all`, `docker stop` fed from a pipe. */
+    readonly unnamed: boolean;
+    /** The fragment, so a card can point at it. */
+    readonly span: CommandSpan;
+    /** Whether a shell would run it, as against a quoted argument of echo or a comment. */
+    readonly live: boolean;
+}
+
+// `ic sandbox <verb>`: the program may be a full path, `ic.exe`, or quoted (`& 'C:\…\ic.exe' sandbox restart work`).
+const IC_INVOCATION = /(?<![\w.$-])ic(?:\.exe)?["']?\s+sandbox\s+([a-z][a-z-]*)(?![\w-])/gi;
+// `docker stop`, `docker container rm`, podman alike. A global option between the program and the verb
+// (`docker -H host stop x`) is not read: the verb then follows an option, and the command is left unrecognised.
+const DOCKER_INVOCATION = /(?<![\w.$-])(?:docker|podman)(?:\.exe)?["']?\s+(?:container\s+)?(stop|restart|rm|remove|kill)(?![\w-])/gi;
+
+const IC_VERBS = new Map<string, SandboxPowerOp>([
+    ["start", "start"],
+    ["stop", "stop"],
+    ["restart", "restart"],
+    ["sleep", "sleep"],
+    ["remove", "remove"],
+    ["rm", "remove"],
+    ["update", "update"],
+    ["prepare", "prepare"],
+    ["rebuild", "rebuild"],
+    ["rollback", "rollback"],
+    ["dev", "dev"],
+    ["reshape", "resize"],
+    ["shape", "resize"],
+    ["backup-restore", "restore"],
+    ["connect", "connect"],
+]);
+
+const DOCKER_VERBS = new Map<string, SandboxPowerOp>([
+    ["stop", "stop"],
+    ["kill", "stop"],
+    ["restart", "restart"],
+    ["rm", "remove"],
+    ["remove", "remove"],
+]);
+
+// The flags of each program that take their value as the next word, so the value is not read as a slug.
+const IC_VALUE_FLAGS: ReadonlySet<string> = new Set([
+    "--channel",
+    "--to",
+    "--set",
+    "--when",
+    "--memory",
+    "--cpus",
+    "--privileged",
+    "--gpus",
+    "--idle",
+    "--source",
+    "--code",
+    "--snapshot",
+    "--into",
+    "--confirm",
+    "--accept",
+    "--tail",
+]);
+const DOCKER_VALUE_FLAGS: ReadonlySet<string> = new Set(["-t", "--time", "-s", "--signal"]);
+
+// The simple command that starts the text: up to the first `|`, `;`, `&` or newline outside quotes. A `&` right after
+// `>` or `<` is a redirection (`2>&1`), which ends nothing.
+const SIMPLE_COMMAND = /^(?:[^|;&\n\r"']|(?<=[<>])&|"[^"]*"?|'[^']*'?)*/;
+// One word, quoted pieces included. Backslashes stay as written: they are Windows path separators as often as escapes,
+// and a slug has neither.
+const WORD = /(?:[^\s"']|"[^"]*"?|'[^']*'?)+/g;
+const REDIRECTION = /^\d*(?:>>?|<)/;
+const BARE_REDIRECTION = /^\d*(?:>>?|<)$/;
+
+const wordsOf = (text: string): string[] => [...(SIMPLE_COMMAND.exec(text)?.[0] ?? "").matchAll(WORD)].map((word) => word[0].replace(/["']/g, ""));
+
+// A redirection (`2>&1`, `> log`, `>>out`) is not an operand; a bare `>` takes the word after it with it.
+const withoutRedirections = (words: readonly string[]): string[] => {
+    const kept: string[] = [];
+    let skipNext = false;
+    for (const word of words) {
+        if (skipNext) {
+            skipNext = false;
+        } else if (BARE_REDIRECTION.test(word)) {
+            skipNext = true;
+        } else if (!REDIRECTION.test(word)) {
+            kept.push(word);
+        }
+    }
+    return kept;
+};
+
+interface Operands {
+    readonly positionals: readonly string[];
+    /** Flags as written, `--flag=value` split: name → value (undefined for a switch). */
+    readonly flags: ReadonlyMap<string, string | undefined>;
+}
+
+const operandsOf = (words: readonly string[], valueFlags: ReadonlySet<string>): Operands => {
+    const positionals: string[] = [];
+    const flags = new Map<string, string | undefined>();
+    const list = withoutRedirections(words);
+    for (const [index, word] of list.entries()) {
+        const equals = word.indexOf("=");
+        if (!word.startsWith("-") || word === "-") {
+            // The word after a flag that takes a value is that value, not an operand.
+            if (!valueFlags.has(list[index - 1] ?? "")) {
+                positionals.push(word);
+            }
+        } else if (word.startsWith("--") && equals !== -1) {
+            flags.set(word.slice(0, equals), word.slice(equals + 1));
+        } else {
+            flags.set(word, valueFlags.has(word) ? list[index + 1] : undefined);
+        }
+    }
+    return { positionals, flags };
+};
+
+interface Aim {
+    readonly stops: boolean;
+    readonly targets: readonly string[];
+    readonly all: boolean;
+}
+
+// What `ic sandbox <op>` with these operands does to a running sandbox, and which sandboxes it aims at. The verbs that
+// restart nothing say so: a start, a download, a resource ask saved for the next restart, a backup restored to a folder.
+const icAim = (op: SandboxPowerOp, { positionals, flags }: Operands): Aim => {
+    const all = flags.has("--all") || flags.has("-a");
+    if (op === "start" || op === "prepare") {
+        return { stops: false, targets: positionals, all };
+    }
+    if (op === "resize") {
+        // `reshape --later` and `--forget` save an ask and restart nothing; `shape` restarts only with `--when now`.
+        const when = flags.get("--when");
+        const saves = flags.has("--later") || flags.has("--forget") || (when !== undefined && when !== "now");
+        return { stops: !saves, targets: positionals, all };
+    }
+    if (op === "restore") {
+        // A backup restored into a folder touches no sandbox; `--into <slug>` stops that one to write its volumes.
+        const into = flags.get("--into");
+        return into === undefined ? { stops: false, targets: [], all: false } : { stops: true, targets: [into], all: false };
+    }
+    if (op === "connect") {
+        return { stops: flags.has("--replace"), targets: [], all: false };
+    }
+    return { stops: true, targets: positionals, all };
+};
+
+/**
+ * Every command in `command` that starts, stops or replaces a sandbox container, through `ic sandbox` or `docker`.
+ * A scan for the programs by name, not a shell parse: it is meant to over-include, since a caller that mistakes
+ * a mention for a command asks the owner once, and one that misses a command cuts a fleet's turns unasked.
+ */
+export const sandboxPowerCommands = (command: string): SandboxPowerCommand[] => {
+    const regions = inertRegions(command);
+    const found: SandboxPowerCommand[] = [];
+    for (const invocation of command.matchAll(IC_INVOCATION)) {
+        const op = IC_VERBS.get((invocation[1] ?? "").toLowerCase());
+        if (op !== undefined) {
+            const span = { start: invocation.index, end: invocation.index + invocation[0].length };
+            const aim = icAim(op, operandsOf(wordsOf(command.slice(span.end)), IC_VALUE_FLAGS));
+            found.push({ via: "ic", op, stops: aim.stops, targets: aim.targets, unnamed: aim.targets.length === 0 || aim.all, span, live: isLive(span, regions) });
+        }
+    }
+    for (const invocation of command.matchAll(DOCKER_INVOCATION)) {
+        const op = DOCKER_VERBS.get((invocation[1] ?? "").toLowerCase());
+        if (op !== undefined) {
+            const span = { start: invocation.index, end: invocation.index + invocation[0].length };
+            const { positionals } = operandsOf(wordsOf(command.slice(span.end)), DOCKER_VALUE_FLAGS);
+            found.push({ via: "docker", op, stops: true, targets: positionals, unnamed: positionals.length === 0, span, live: isLive(span, regions) });
+        }
+    }
+    return found.toSorted((left, right) => left.span.start - right.span.start);
+};
+
+// A word whose value exists only when the shell runs it: `$(docker ps -q)`, `$NAME`, `*`, PowerShell's `(…)` and `%X%`.
+const isExpansion = (word: string): boolean => /[$`*?%]|^\(/.test(word);
+
+/** The sandbox a caller means to protect: its slug, and the container name docker knows it by. */
+export interface OwnSandbox {
+    readonly slug: string;
+    readonly container: string;
+}
+
+/**
+ * Whether `hit` may stop `own`. Deliberately generous: it names it, names none (the device's only sandbox, `--all`, a
+ * pipe), or names something that is only worked out when the command runs. A target spelled as the bare slug counts for
+ * `docker` too, which knows the container by a longer name.
+ */
+export const mayReachSandbox = (hit: SandboxPowerCommand, own: OwnSandbox): boolean =>
+    hit.unnamed || hit.targets.some((target) => target === own.slug || target === own.container || isExpansion(target));
+
+/**
+ * Whether `hit` manages a sandbox that a device's "Manage sandboxes" switch covers, whichever sandbox it is: any
+ * `ic sandbox` verb here, and a `docker` verb aimed at a container whose name starts with `containerPrefix` (a sandbox's
+ * own, or its tunnel's). A docker target worked out at run time is not read: the device cannot know what it will be.
+ */
+export const managesSandbox = (hit: SandboxPowerCommand, containerPrefix: string): boolean =>
+    hit.via === "ic" || hit.targets.some((target) => target.startsWith(containerPrefix));

package/src/policy/search-globs.ts

@@ -58,3 +58,138 @@ export const includeGlobs = (include: string | undefined): IncludeGlobs => {
         notGlobs: segments.filter((segment) => segment.startsWith(`!`)).flatMap((segment) => expand(segment.slice(1))),
     };
 };
+
+// ONE GLOB MATCHER, with Bun.Glob's reading of every construct, so the daemon, the desktop folder server (which runs
+// Bun.Glob itself) and the demo admit the same files for the same pattern. Before this the daemon's copy took
+// `[!t]` as a set of the characters `!` and `t`, where Bun.Glob reads "anything but t".
+// - `*` is any run within one path segment, `?` one character of it
+// - `**` as a whole segment is any number of segments, none included (`**/x` matches `x`); inside a segment it is `*`
+// - `[abc]`, `[a-z]`, and `[!abc]` or `[^abc]` for "none of these"; a `]` first in the set is literal
+// - `{a,b}` is either, nested groups and globs inside included; `\` makes the next character literal
+// - an unclosed `[` or `{` is literal, where Bun.Glob matches nothing: a half-typed pattern then still finds its text
+const REGEXP_SPECIAL = /[.*+?^${}()|[\]\\/]/;
+
+const literal = (char: string): string => (REGEXP_SPECIAL.test(char) ? `\\${char}` : char);
+
+// The index of the `]` closing the set opened at `open`, or -1.
+const setEnd = (glob: string, open: number): number => {
+    let index = open + 1;
+    if (glob[index] === `!` || glob[index] === `^`) {
+        index += 1;
+    }
+    // A `]` straight after the opening (or its negation) is a member, not the close.
+    if (glob[index] === `]`) {
+        index += 1;
+    }
+    for (; index < glob.length; index += 1) {
+        if (glob[index] === `\\`) {
+            index += 1;
+        } else if (glob[index] === `]`) {
+            return index;
+        }
+    }
+    return -1;
+};
+
+const setSource = (body: string): string => {
+    const negated = body.startsWith(`!`) || body.startsWith(`^`);
+    const members = (negated ? body.slice(1) : body).replaceAll(/\\(.)/g, `$1`).replaceAll(/[\\\]^[]/g, (char) => `\\${char}`);
+    return `[${negated ? `^` : ``}${members}]`;
+};
+
+// The index of the `}` closing the group opened at `open`, and where its top-level commas fall; undefined if unclosed.
+const groupOf = (glob: string, open: number): { readonly end: number; readonly commas: readonly number[] } | undefined => {
+    const commas: number[] = [];
+    let depth = 0;
+    for (let index = open; index < glob.length; index += 1) {
+        const char = glob[index];
+        if (char === `\\`) {
+            index += 1;
+        } else if (char === `[`) {
+            const end = setEnd(glob, index);
+            index = end === -1 ? index : end;
+        } else if (char === `{`) {
+            depth += 1;
+        } else if (char === `}`) {
+            depth -= 1;
+            if (depth === 0) {
+                return { end: index, commas };
+            }
+        } else if (char === `,` && depth === 1) {
+            commas.push(index);
+        }
+    }
+    return undefined;
+};
+
+// `**` filling a whole segment: the source it stands for and how many characters of the glob it consumed.
+const globstar = (glob: string, index: number, segmentStart: boolean): { readonly source: string; readonly length: number } | undefined => {
+    if (!segmentStart || glob[index + 1] !== `*`) {
+        return undefined;
+    }
+    const after = glob[index + 2];
+    if (after === `/`) {
+        return { source: `(?:[^/]*/)*`, length: 3 };
+    }
+    return after === undefined ? { source: `.*`, length: 2 } : undefined;
+};
+
+const compileGlob = (glob: string, segmentStart: boolean): string => {
+    let source = ``;
+    let atStart = segmentStart;
+    for (let index = 0; index < glob.length; index += 1) {
+        const char = glob[index]!;
+        const star = char === `*` ? globstar(glob, index, atStart) : undefined;
+        if (star !== undefined) {
+            source += star.source;
+            index += star.length - 1;
+            atStart = true;
+            continue;
+        }
+        if (char === `*`) {
+            // A run of stars inside a segment is one star.
+            while (glob[index + 1] === `*`) {
+                index += 1;
+            }
+            source += `[^/]*`;
+        } else if (char === `?`) {
+            source += `[^/]`;
+        } else if (char === `\\` && index + 1 < glob.length) {
+            index += 1;
+            source += literal(glob[index]!);
+        } else if (char === `[` && setEnd(glob, index) !== -1) {
+            const end = setEnd(glob, index);
+            source += setSource(glob.slice(index + 1, end));
+            index = end;
+        } else if (char === `{` && groupOf(glob, index) !== undefined) {
+            const group = groupOf(glob, index)!;
+            const bounds = [index, ...group.commas, group.end];
+            const alternatives = bounds.slice(1).map((end, at) => compileGlob(glob.slice(bounds[at]! + 1, end), atStart));
+            source += `(?:${alternatives.join(`|`)})`;
+            index = group.end;
+        } else {
+            source += literal(char);
+        }
+        atStart = char === `/`;
+    }
+    return source;
+};
+
+// The whole path must match: `*.ts` is a name at the root, not a suffix anywhere.
+export const globRegExp = (glob: string): RegExp => new RegExp(`^${compileGlob(glob, true)}$`);
+
+// A matcher for slash-separated relative paths, compiled once.
+export const globMatcher = (glob: string): ((path: string) => boolean) => {
+    const pattern = globRegExp(glob);
+    return (path) => pattern.test(path);
+};
+
+// The search box's whole second field as one test over a relative path: admitted by any include (or by none being
+// typed), and by no exclude. An anchored include's `./` is the root, so it is dropped before matching.
+export const includeMatcher = (include: string | undefined): ((path: string) => boolean) => {
+    const { globs, notGlobs } = includeGlobs(include);
+    const rooted = (glob: string): string => glob.replace(/^\.\//, ``);
+    const admits = globs.map((glob) => globMatcher(rooted(glob)));
+    const refuses = notGlobs.map((glob) => globMatcher(rooted(glob)));
+    return (path) => (admits.length === 0 || admits.some((test) => test(path))) && !refuses.some((test) => test(path));
+};

package/src/policy/secret-hosts.ts

@@ -42,6 +42,13 @@ export const normalizeHost = (raw: string): string | undefined => {
 export const hostMatches = (pattern: string, host: string): boolean =>
     pattern.startsWith(WILDCARD) ? host.endsWith(pattern.slice(1)) : host === pattern;
 
+// Whether one entry of a domain list covers a host: a plain entry names a domain and every host under it at any depth
+// (`example.com` covers `example.com` and `api.example.com`, never `notexample.com`), a wildcard only the hosts under it.
+// Both sides are expected normalized. The wallet's allow and deny lists read their entries this way; a secret's host
+// guard reads its own exactly (hostMatches).
+export const hostCovers = (entry: string, host: string): boolean =>
+    entry.startsWith(WILDCARD) ? hostMatches(entry, host) : host === entry || host.endsWith(`.${entry}`);
+
 export const hostAllowed = (patterns: readonly string[], host: string): boolean => patterns.some((pattern) => hostMatches(pattern, host));
 
 // Whether every host `pattern` matches is already matched by `patterns`: an exact host by any pattern that matches it, a