@intentic/sandbox-contract 1.337.0 → 1.339.0

package/src/schemas/intentic-os.ts

@@ -128,3 +128,262 @@ export const icOsRebootArgs = (): string[] => ["os", "reboot"];
 // Checked here too, not only by a caller's schema: a channel is a positional, and one beginning with a hyphen would
 // reach ic as a flag.
 export const icOsChannelArgs = (channel: IntenticOsChannel): string[] => ["os", "channel", IntenticOsChannelSchema.parse(channel)];
+
+// THE MACHINE'S OWN SETTINGS (2026-10-16): the network, the sound, the screen, the keyboard and the drives a person plugs
+// in, each a verb of `ic os` (_os/README.md, "Settings"). The desktop app's This computer cards, its status bar and the
+// machine agent's tools all read these shapes, so a person and the agent in the machine's own sandbox change the same
+// things the same way ("connect to the guest Wi-Fi"). ic reads NetworkManager, WirePlumber, sway and udisks for them:
+// nothing that calls ic speaks to those.
+
+/** Exit code of the screen verbs (display, keyboard) on an edition with no screen (the server edition). */
+export const IC_OS_NO_SCREEN_EXIT = 4;
+
+/** Exit code of `ic os network wifi connect` when the network needs a password it was not given, or refused the one it
+ *  was: ask the person for it and try again with `--password-stdin`. */
+export const IC_OS_WIFI_PASSWORD_EXIT = 5;
+
+/** Exit code of `ic os drives import` when what is on the drive would not fit in the sandbox: nothing was copied. */
+export const IC_OS_DRIVE_NO_ROOM_EXIT = 6;
+
+// `ic os network status --json`: how this machine is online right now. `name` is the Wi-Fi network's name or the wired
+// connection's, `signal` the Wi-Fi strength 0-100 (null on a wire and offline). The status bar reads exactly this.
+export const IntenticOsNetworkKindSchema = z.enum(["wifi", "ethernet", "none"]);
+export type IntenticOsNetworkKind = z.infer<typeof IntenticOsNetworkKindSchema>;
+
+const percent = z.number().int().min(0).max(100);
+
+export const IntenticOsNetworkStatusSchema = z.object({
+    connected: z.boolean(),
+    kind: IntenticOsNetworkKindSchema,
+    name: z.string().nullable(),
+    signal: percent.nullable(),
+});
+export type IntenticOsNetworkStatus = z.infer<typeof IntenticOsNetworkStatusSchema>;
+
+// One Wi-Fi network in reach, once however many access points broadcast it: the strongest signal, `secured` when it
+// asks for a password, `known` when this machine has joined it before (it rejoins without asking), `active` when it is
+// the one in use.
+export const IntenticOsWifiNetworkSchema = z.object({
+    ssid: z.string(),
+    signal: percent,
+    secured: z.boolean(),
+    known: z.boolean(),
+    active: z.boolean(),
+});
+export type IntenticOsWifiNetwork = z.infer<typeof IntenticOsWifiNetworkSchema>;
+
+// `ic os network wifi list --json`: `adapter` false on a machine with no Wi-Fi, `enabled` false while Wi-Fi is turned
+// off (then `networks` is empty), the networks strongest first.
+export const IntenticOsWifiListSchema = z.object({
+    adapter: z.boolean(),
+    enabled: z.boolean(),
+    networks: z.array(IntenticOsWifiNetworkSchema),
+});
+export type IntenticOsWifiList = z.infer<typeof IntenticOsWifiListSchema>;
+
+// `ic os sound status --json`: the volume of what plays now, 0-100, whether it is muted, and the speaker or headphones it
+// plays on (null when this machine has none). The status bar reads exactly this.
+export const IntenticOsSoundStatusSchema = z.object({
+    volume: percent,
+    muted: z.boolean(),
+    output: z.string().nullable(),
+});
+export type IntenticOsSoundStatus = z.infer<typeof IntenticOsSoundStatusSchema>;
+
+// `ic os sound outputs --json`: every speaker, headphone and screen that plays sound, `default` on the one in use.
+// `id` is what `ic os sound output <id>` takes; it can change when a device is plugged in again.
+export const IntenticOsSoundOutputSchema = z.object({
+    id: z.number().int().nonnegative(),
+    name: z.string(),
+    default: z.boolean(),
+});
+export type IntenticOsSoundOutput = z.infer<typeof IntenticOsSoundOutputSchema>;
+export const IntenticOsSoundOutputsSchema = z.object({ outputs: z.array(IntenticOsSoundOutputSchema) });
+export type IntenticOsSoundOutputs = z.infer<typeof IntenticOsSoundOutputsSchema>;
+
+// A screen's mode: pixels across and down, and how many times a second it redraws (Hz, to three decimals).
+export const IntenticOsDisplayModeSchema = z.object({
+    width: z.number().int().positive(),
+    height: z.number().int().positive(),
+    refresh: z.number().nonnegative(),
+});
+export type IntenticOsDisplayMode = z.infer<typeof IntenticOsDisplayModeSchema>;
+
+// One screen as `ic os display list --json` says it: `name` is the connector (`HDMI-A-1`, `eDP-1`) every other verb
+// names it by, `make` and `model` what the screen says it is (null where it does not), `current` the mode it shows now
+// (null while it is off), `modes` every mode it offers, `scale` how much bigger everything is drawn (null while off).
+export const IntenticOsDisplaySchema = z.object({
+    name: z.string(),
+    make: z.string().nullable(),
+    model: z.string().nullable(),
+    enabled: z.boolean(),
+    current: IntenticOsDisplayModeSchema.nullable(),
+    modes: z.array(IntenticOsDisplayModeSchema),
+    scale: z.number().positive().nullable(),
+});
+export type IntenticOsDisplay = z.infer<typeof IntenticOsDisplaySchema>;
+export const IntenticOsDisplayListSchema = z.object({ outputs: z.array(IntenticOsDisplaySchema) });
+export type IntenticOsDisplayList = z.infer<typeof IntenticOsDisplayListSchema>;
+
+// `ic os keyboard status --json`: the layout in use as xkb names it (`us`, `de`), its variant (`nodeadkeys`, null for
+// the layout's own), and its name for a person ("German (no dead keys)"), null when xkb has none for it.
+export const IntenticOsKeyboardStatusSchema = z.object({
+    layout: z.string(),
+    variant: z.string().nullable(),
+    name: z.string().nullable(),
+});
+export type IntenticOsKeyboardStatus = z.infer<typeof IntenticOsKeyboardStatusSchema>;
+
+export const IntenticOsKeyboardVariantSchema = z.object({ variant: z.string(), name: z.string() });
+export const IntenticOsKeyboardLayoutSchema = z.object({
+    layout: z.string(),
+    name: z.string(),
+    variants: z.array(IntenticOsKeyboardVariantSchema),
+});
+export type IntenticOsKeyboardLayout = z.infer<typeof IntenticOsKeyboardLayoutSchema>;
+// `ic os keyboard layouts --json`: every layout xkb knows, in its own order, each with its variants.
+export const IntenticOsKeyboardLayoutsSchema = z.object({ layouts: z.array(IntenticOsKeyboardLayoutSchema) });
+export type IntenticOsKeyboardLayouts = z.infer<typeof IntenticOsKeyboardLayoutsSchema>;
+
+// What kind of removable drive: a USB stick or disk, or a memory card in a card reader.
+export const IntenticOsDriveKindSchema = z.enum(["usb", "card", "other"]);
+export type IntenticOsDriveKind = z.infer<typeof IntenticOsDriveKindSchema>;
+
+// One removable drive's filesystem (a partition, or the whole stick when it has none) as `ic os drives list --json`
+// says it: `device` is what the other drive verbs take, `label` the name it was given (null for none), `size` in bytes,
+// `filesystem` as Linux names it (`vfat`, `exfat`, `ntfs`, `ext4`), `mountedAt` where it is open (null while it is
+// not), `model` what the drive says it is. The machine's own disks are never listed.
+export const IntenticOsDriveSchema = z.object({
+    device: z.string(),
+    label: z.string().nullable(),
+    size: z.number().int().nonnegative(),
+    filesystem: z.string().nullable(),
+    mountedAt: z.string().nullable(),
+    readOnly: z.boolean(),
+    model: z.string().nullable(),
+    kind: IntenticOsDriveKindSchema,
+});
+export type IntenticOsDrive = z.infer<typeof IntenticOsDriveSchema>;
+export const IntenticOsDrivesSchema = z.object({ drives: z.array(IntenticOsDriveSchema) });
+export type IntenticOsDrives = z.infer<typeof IntenticOsDrivesSchema>;
+
+// `ic os drives import … --json` prints one of these every few seconds while it copies, then the result last.
+export const IntenticOsDriveImportProgressSchema = z.object({
+    progress: z.object({ bytes: z.number().int().nonnegative(), total: z.number().int().nonnegative() }),
+});
+export type IntenticOsDriveImportProgress = z.infer<typeof IntenticOsDriveImportProgressSchema>;
+
+// What was copied: from which drive, into which sandbox, the folder inside it (`/work/Imports/<label>-<date>`), and how
+// many bytes in how many files.
+export const IntenticOsDriveImportSchema = z.object({
+    device: z.string(),
+    sandbox: z.string(),
+    path: z.string(),
+    bytes: z.number().int().nonnegative(),
+    files: z.number().int().nonnegative(),
+});
+export type IntenticOsDriveImport = z.infer<typeof IntenticOsDriveImportSchema>;
+
+// The pieces a caller hands ic as positionals and flag values, checked here before they reach its command line: none may
+// begin with a hyphen (it would be a flag), and none is a path out of where it belongs. An SSID is anything a network
+// broadcasts, so it goes after `--` instead.
+const OUTPUT_NAME = /^[A-Za-z0-9][A-Za-z0-9_.-]{0,63}$/;
+const XKB_NAME = /^[A-Za-z0-9][A-Za-z0-9_+-]{0,63}$/;
+const BLOCK_DEVICE = /^\/dev\/[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+const SANDBOX_SLUG = /^[A-Za-z0-9][A-Za-z0-9_.-]{0,127}$/;
+
+// An SSID is at most 32 bytes, in whatever characters the network broadcasts.
+export const IntenticOsSsidSchema = z
+    .string()
+    .min(1)
+    .refine((ssid) => new TextEncoder().encode(ssid).length <= 32, "a Wi-Fi network's name, at most 32 bytes");
+export const IntenticOsDisplayNameSchema = z.string().regex(OUTPUT_NAME, "a screen's connector name, like HDMI-A-1");
+export const IntenticOsXkbNameSchema = z.string().regex(XKB_NAME, "an xkb layout or variant name, like de or nodeadkeys");
+export const IntenticOsBlockDeviceSchema = z.string().regex(BLOCK_DEVICE, "a drive's device, like /dev/sdb1");
+export const IntenticOsSandboxSlugSchema = z.string().regex(SANDBOX_SLUG, "a sandbox's slug").refine((slug) => !slug.includes(".."), "a sandbox's slug");
+// A folder inside the sandbox's /work: relative, no `..`, no leading slash or hyphen.
+export const IntenticOsImportPathSchema = z
+    .string()
+    .min(1)
+    .max(255)
+    .refine(
+        (path) => !path.startsWith("/") && !path.startsWith("-") && path.split("/").every((part) => part !== ".." && part !== "." && part !== ""),
+        "a folder inside the sandbox's /work, like Photos/2026",
+    );
+export const IntenticOsScaleSchema = z.number().min(0.5).max(4);
+
+/** A mode the way `ic os display set --mode` takes it: `1920x1080@60`, the rate to three decimals at most. */
+export const displayModeArg = (mode: IntenticOsDisplayMode): string => `${mode.width}x${mode.height}@${Number(mode.refresh.toFixed(3))}`;
+
+export const icOsNetworkStatusArgs = (): string[] => ["os", "network", "status", "--json"];
+export const icOsWifiListArgs = (): string[] => ["os", "network", "wifi", "list", "--json"];
+// The password never: it goes on ic's stdin with `--password-stdin`, since a command line is readable by anyone on the
+// machine (`ps`). Without one, ic joins a known network or one that asks for none, and exits IC_OS_WIFI_PASSWORD_EXIT
+// for one that needs a password.
+export const icOsWifiConnectArgs = (ssid: string, withPassword: boolean): string[] => [
+    "os",
+    "network",
+    "wifi",
+    "connect",
+    ...(withPassword ? ["--password-stdin"] : []),
+    "--",
+    IntenticOsSsidSchema.parse(ssid),
+];
+export const icOsWifiForgetArgs = (ssid: string): string[] => ["os", "network", "wifi", "forget", "--", IntenticOsSsidSchema.parse(ssid)];
+export const icOsWifiRadioArgs = (on: boolean): string[] => ["os", "network", "wifi", on ? "on" : "off"];
+
+export const icOsSoundStatusArgs = (): string[] => ["os", "sound", "status", "--json"];
+// At least one of the two: a volume 0-100, and muted or not. Answers with the status after (`--json`).
+export const icOsSoundSetArgs = (change: { readonly volume?: number; readonly muted?: boolean }): string[] => {
+    const args = ["os", "sound", "set"];
+    if (change.volume !== undefined) {
+        args.push("--volume", String(percent.parse(Math.round(change.volume))));
+    }
+    if (change.muted !== undefined) {
+        args.push(change.muted ? "--mute" : "--unmute");
+    }
+    if (args.length === 3) {
+        throw new Error("a sound change names a volume, muted, or both");
+    }
+    return [...args, "--json"];
+};
+export const icOsSoundOutputsArgs = (): string[] => ["os", "sound", "outputs", "--json"];
+export const icOsSoundOutputArgs = (id: number): string[] => ["os", "sound", "output", String(z.number().int().nonnegative().parse(id))];
+
+export const icOsDisplayListArgs = (): string[] => ["os", "display", "list", "--json"];
+export const icOsDisplaySetArgs = (output: string, change: { readonly mode?: IntenticOsDisplayMode; readonly scale?: number }): string[] => {
+    const args = ["os", "display", "set", IntenticOsDisplayNameSchema.parse(output)];
+    if (change.mode !== undefined) {
+        args.push("--mode", displayModeArg(IntenticOsDisplayModeSchema.parse(change.mode)));
+    }
+    if (change.scale !== undefined) {
+        args.push("--scale", String(IntenticOsScaleSchema.parse(change.scale)));
+    }
+    if (args.length === 4) {
+        throw new Error("a display change names a mode, a scale, or both");
+    }
+    return args;
+};
+
+export const icOsKeyboardStatusArgs = (): string[] => ["os", "keyboard", "status", "--json"];
+export const icOsKeyboardLayoutsArgs = (): string[] => ["os", "keyboard", "layouts", "--json"];
+export const icOsKeyboardSetArgs = (layout: string, variant?: string): string[] => [
+    "os",
+    "keyboard",
+    "set",
+    IntenticOsXkbNameSchema.parse(layout),
+    ...(variant === undefined ? [] : ["--variant", IntenticOsXkbNameSchema.parse(variant)]),
+];
+
+export const icOsDrivesListArgs = (): string[] => ["os", "drives", "list", "--json"];
+export const icOsDriveImportArgs = (device: string, sandbox: string, path?: string): string[] => [
+    "os",
+    "drives",
+    "import",
+    IntenticOsBlockDeviceSchema.parse(device),
+    "--to",
+    IntenticOsSandboxSlugSchema.parse(sandbox),
+    ...(path === undefined ? [] : ["--path", IntenticOsImportPathSchema.parse(path)]),
+    "--json",
+];
+export const icOsDriveEjectArgs = (device: string): string[] => ["os", "drives", "eject", IntenticOsBlockDeviceSchema.parse(device)];

package/src/schemas/keyring.ts

@@ -0,0 +1,277 @@
+import { z } from "zod";
+
+// Secrets that live in a keyring on the owner's own computer (`intentic-keyring`, a process of its own beside
+// intentic-machine) rather than in the sandbox. The sandbox holds a POINTER to each one shared with it, never the value,
+// and asks for a value by sending a grant it signed: the machine relays the grant to the keyring and the answer back,
+// and the answer is sealed to whoever the grant names, so the machine carries only ciphertext. What a grant may ask for
+// is the keyring's to decide (its share mode, its program list, a person's tap); the sandbox's own gates run first.
+// The sealing and signing themselves are policy/keyring-seal.ts.
+
+// Raw 32-byte keys travel as base64url without padding, the `x` of their JWK: X25519 for sealing, Ed25519 for signing.
+export const KEYRING_KEY_RE = /^[A-Za-z0-9_-]{43}$/u;
+export const KeyringPublicKeySchema = z.string().regex(KEYRING_KEY_RE).describe("A raw 32-byte public key, base64url without padding.");
+
+// One secret's name, the same shape a sandbox secret's name and a reference to it take (SECRET_KEY_RE), so a shared
+// entry is spent, typed and listed exactly like a sandbox-held one.
+export const KEYRING_NAME_RE = /^[A-Za-z_][A-Za-z0-9_]{0,127}$/u;
+export const KeyringSecretNameSchema = z
+    .string()
+    .regex(KEYRING_NAME_RE)
+    .describe("The secret's name, as a reference to it carries it: a letter or underscore, then letters, digits or `_`.");
+
+export const KeyringShareModeSchema = z
+    .enum(["each-use", "while-here", "copy"])
+    .describe(
+        "How the keyring answers this sandbox: `each-use` asks the person at the computer every time (Windows Hello, or the keyring's passphrase); `while-here` answers unasked while the keyring is unlocked, for as long as the unlock lasts; `copy` keeps a copy in the sandbox, so it works with the computer off, which makes it an ordinary sandbox secret.",
+    );
+export type KeyringShareMode = z.infer<typeof KeyringShareModeSchema>;
+
+// A program a value may be typed into without asking: an executable's file name (`FortiClient.exe`, matched without case)
+// or its whole path. Android apps are package names, kept apart in `packages`.
+export const KEYRING_PROGRAM_MAX = 260;
+export const KeyringProgramSchema = z
+    .string()
+    .min(1)
+    .max(KEYRING_PROGRAM_MAX)
+    .refine((value) => !/[\0\r\n]/u.test(value), "one program per entry, no line breaks")
+    .describe("A program, by its executable's file name (`FortiClient.exe`, `mstsc.exe`, `ssh`) or its whole path.");
+export const KEYRING_PACKAGE_RE = /^[A-Za-z][A-Za-z0-9_]*(\.[A-Za-z0-9_]+)+$/u;
+export const KeyringPackageSchema = z.string().regex(KEYRING_PACKAGE_RE).max(255).describe("An Android app, by its package name (`com.fortinet.forticlient`).");
+export const KEYRING_PROGRAMS_MAX = 32;
+
+export const KeyringSourceSchema = z
+    .enum(["keyring", "bitwarden", "1password", "keepassxc"])
+    .describe("Where the value itself is read from when it is used: the keyring's own vault, or a password manager the keyring reads it from.");
+export type KeyringSource = z.infer<typeof KeyringSourceSchema>;
+
+// What the keyring tells a sandbox about one entry shared with it: everything the sandbox needs to list it, mask it
+// once released and judge a use before asking, never the value.
+export const KeyringPointerSchema = z.object({
+    name: KeyringSecretNameSchema,
+    mode: KeyringShareModeSchema,
+    kind: z.enum(["password", "text"]).describe("A password, typed only into a password field unless `anyField` says otherwise; or text, typed anywhere a program on the list has focus."),
+    programs: z
+        .array(KeyringProgramSchema)
+        .max(KEYRING_PROGRAMS_MAX)
+        .describe("Programs on this computer it may be typed into without asking. Empty: typing it into any window asks the person at the computer."),
+    packages: z.array(KeyringPackageSchema).max(KEYRING_PROGRAMS_MAX).describe("Android apps on a phone attached to this computer it may be typed into."),
+    hosts: z
+        .array(z.string().min(1).max(253))
+        .max(KEYRING_PROGRAMS_MAX)
+        .describe("Sites it may be typed into or sent to, exact or `*.domain`, the same shape as a sandbox secret's host guard."),
+    anyField: z.boolean().describe("Whether it may be typed into a field the program does not mark as a password field."),
+    source: KeyringSourceSchema,
+    updatedAt: z.number().describe("When the entry last changed, in milliseconds."),
+});
+export type KeyringPointer = z.infer<typeof KeyringPointerSchema>;
+
+// The keyring's own public keys: `seal` for a value the sandbox sends it to type (a sandbox-held secret, or one another
+// computer released for this one), `inbox` for a value sent to be kept, readable only once the vault is unlocked.
+export const KeyringDeviceKeysSchema = z.object({
+    seal: KeyringPublicKeySchema.describe("Seals a value this keyring is asked to type. Its private half sits beside the vault, readable while locked."),
+    inbox: KeyringPublicKeySchema.describe("Seals a value sent to be kept. Its private half is inside the vault, so nothing reads an inbox item until a person unlocks it."),
+});
+export type KeyringDeviceKeys = z.infer<typeof KeyringDeviceKeysSchema>;
+
+// A sandbox's own keyring keys, served unauthenticated at GET /keyring/keys so a keyring can fetch them over TLS from the
+// sandbox's address itself rather than take them from whoever relays a share: `sign` verifies its grants, `seal` is what
+// a released value is sealed to.
+export const KeyringSandboxKeysSchema = z.object({
+    sign: KeyringPublicKeySchema.describe("Verifies the grants this sandbox signs (Ed25519)."),
+    seal: KeyringPublicKeySchema.describe("What a value released to this sandbox is sealed to (X25519)."),
+});
+export type KeyringSandboxKeys = z.infer<typeof KeyringSandboxKeysSchema>;
+
+export const KeyringStateSchema = z.object({
+    version: z.string().describe("The keyring's own release."),
+    locked: z.boolean().describe("Whether the vault is locked. Locked, `while-here` entries ask like `each-use` ones."),
+    unlockedUntil: z.number().optional().describe("When the current unlock ends, in milliseconds. Absent while locked."),
+    unlock: z
+        .array(z.enum(["hello", "passphrase"]))
+        .describe("How a person unlocks it here: Windows Hello, or the keyring's passphrase."),
+    keys: KeyringDeviceKeysSchema.optional().describe("Absent until the keyring is set up: there is no vault, so no inbox to seal a value to."),
+    pendingInbox: z.number().int().nonnegative().describe("Values sent to be kept that wait for the next unlock."),
+});
+export type KeyringState = z.infer<typeof KeyringStateSchema>;
+
+// The machine's answer to `keyringShares`: the keyring's state and the entries shared with the asking sandbox. Absent
+// `keyring`: none is installed, or it does not answer.
+export const KeyringSharesSchema = z.object({
+    keyring: KeyringStateSchema.optional().describe("The keyring on this computer. Absent when none is installed or it does not answer."),
+    pointers: z.array(KeyringPointerSchema).describe("The entries shared with the sandbox asking. Names and rules only, never values."),
+    reason: z.string().optional().describe("Why there is no keyring to speak of, in words, when there is not."),
+});
+export type KeyringShares = z.infer<typeof KeyringSharesSchema>;
+
+// ---- grants ----
+
+export const KeyringLaneSchema = z
+    .enum(["shell", "code", "browser", "desktop"])
+    .describe("Where in the sandbox a released value goes: a command, a script, a page in a sandbox browser, a window on the sandbox's desktop.");
+
+// What a grant asks the keyring to do with one value.
+export const KeyringGrantTargetSchema = z.discriminatedUnion("kind", [
+    // Hand the value to the sandbox, sealed to its pinned `seal` key, for one use in one lane.
+    z.object({ kind: z.literal("sandbox"), lane: KeyringLaneSchema }),
+    // Type it into the focused window on this computer. `programs` and `anyField` are the sandbox's own guard for a
+    // value it sent; for the keyring's own entry the keyring's list is the one in force and these only narrow it.
+    z.object({
+        kind: z.literal("window"),
+        programs: z.array(KeyringProgramSchema).max(KEYRING_PROGRAMS_MAX),
+        anyField: z.boolean(),
+        // The owner's own Type into…, from the editor: a moment to put the cursor where the value goes.
+        countdownSeconds: z.number().int().min(0).max(10).optional(),
+    }),
+    // Type it on an Android phone attached to this computer, into one of these apps.
+    z.object({ kind: z.literal("android"), serial: z.string().min(1).max(128), packages: z.array(KeyringPackageSchema).max(KEYRING_PROGRAMS_MAX) }),
+    // Seal it to another computer's keyring, which the sandbox then asks to type it: the value goes computer to computer
+    // and the sandbox carries only ciphertext.
+    z.object({ kind: z.literal("relay"), sealTo: KeyringPublicKeySchema, toMachine: z.string().min(1).max(128) }),
+]);
+export type KeyringGrantTarget = z.infer<typeof KeyringGrantTargetSchema>;
+
+// A grant lives two minutes at most: long enough for a person to answer a Windows Hello prompt, short enough that one
+// lifted from a log is spent or stale.
+export const KEYRING_GRANT_TTL_MAX_MS = 2 * 60_000;
+export const KEYRING_NONCE_RE = /^[A-Za-z0-9_-]{22}$/u;
+
+export const KeyringGrantSchema = z
+    .object({
+        v: z.literal(1),
+        sandbox: z.string().url().describe("The sandbox's own address: which share this grant spends, and whose signing key verifies it."),
+        secret: KeyringSecretNameSchema,
+        target: KeyringGrantTargetSchema,
+        purpose: z.enum(["agent", "owner"]).describe("Whether an agent asked for this use, or the owner did from the editor's Type into…."),
+        conversation: z.string().max(200).optional().describe("The conversation the use is for, shown in the keyring's prompt and its record."),
+        detail: z.string().min(1).max(300).describe("What the use is, in words, for the person answering the prompt: the command's start, the site, the window."),
+        nonce: z.string().regex(KEYRING_NONCE_RE).describe("16 random bytes, base64url: a grant answers once."),
+        issuedAt: z.number().int(),
+        expiresAt: z.number().int(),
+    })
+    .strict();
+export type KeyringGrant = z.infer<typeof KeyringGrantSchema>;
+
+export const SignedKeyringGrantSchema = z
+    .object({
+        payload: z.string().min(1).max(8192).describe("The grant's JSON, base64url."),
+        sig: z.string().regex(/^[A-Za-z0-9_-]{86}$/u).describe("The sandbox's Ed25519 signature over the grant, base64url."),
+    })
+    .strict();
+export type SignedKeyringGrant = z.infer<typeof SignedKeyringGrantSchema>;
+
+// X25519 to the recipient's key with a fresh key per box, HKDF-SHA256, AES-256-GCM; the additional data binds a box to
+// what it was sealed for (policy/keyring-seal.ts), so one cannot be replayed as another.
+export const SealedBoxSchema = z
+    .object({
+        v: z.literal(1),
+        epk: KeyringPublicKeySchema.describe("The sender's one-time public key."),
+        iv: z.string().regex(/^[A-Za-z0-9_-]{16}$/u),
+        tag: z.string().regex(/^[A-Za-z0-9_-]{22}$/u),
+        data: z.string().max(65536).regex(/^[A-Za-z0-9_-]*$/u),
+    })
+    .strict();
+export type SealedBox = z.infer<typeof SealedBoxSchema>;
+
+export const KeyringRefusalCodeSchema = z
+    .enum(["no-keyring", "locked", "declined", "unknown", "not-shared", "bad-grant", "expired", "replayed", "guard", "unavailable", "busy"])
+    .describe(
+        "Why: no keyring here; locked with nobody to unlock it; the person said no; no such entry; not shared with this sandbox; a grant that does not verify; one past its time; one already spent; the focused window or field is not one it may go to; its password manager did not answer; another prompt is open.",
+    );
+export type KeyringRefusalCode = z.infer<typeof KeyringRefusalCodeSchema>;
+
+const refusal = z.object({ ok: z.literal(false), code: KeyringRefusalCodeSchema, refusal: z.string().describe("What happened, in words a person can act on.") });
+
+export const KeyringReleaseResultSchema = z.discriminatedUnion("ok", [
+    z.object({ ok: z.literal(true), sealed: SealedBoxSchema, asked: z.boolean().describe("Whether the person at the computer was asked.") }),
+    refusal,
+]);
+export type KeyringReleaseResult = z.infer<typeof KeyringReleaseResultSchema>;
+
+export const KeyringTypeInputSchema = z
+    .object({
+        grant: SignedKeyringGrantSchema,
+        // A value the keyring does not hold itself: a sandbox-held secret, or one another computer released for this one,
+        // sealed to this keyring's `seal` key.
+        sealed: SealedBoxSchema.optional(),
+    })
+    .strict();
+export type KeyringTypeInput = z.infer<typeof KeyringTypeInputSchema>;
+
+export const KeyringTypeResultSchema = z.discriminatedUnion("ok", [
+    z.object({
+        ok: z.literal(true),
+        program: z.string().describe("The program it was typed into: its executable's file name, or the Android app's package."),
+        field: z.enum(["password", "text"]).describe("Whether the focused field was a password field."),
+        asked: z.boolean().describe("Whether the person at the computer was asked."),
+    }),
+    refusal,
+]);
+export type KeyringTypeResult = z.infer<typeof KeyringTypeResultSchema>;
+
+// A value sent from the sandbox to be kept in this computer's keyring (a `secrets ask` answered with "keep it on my
+// computer"), sealed to the vault's inbox key and taken in at the next unlock, when the person sees its name and says yes.
+export const KeyringInboxItemSchema = z
+    .object({
+        name: KeyringSecretNameSchema,
+        sealed: SealedBoxSchema,
+        mode: KeyringShareModeSchema,
+        kind: z.enum(["password", "text"]),
+        programs: z.array(KeyringProgramSchema).max(KEYRING_PROGRAMS_MAX),
+        hosts: z.array(z.string().min(1).max(253)).max(KEYRING_PROGRAMS_MAX),
+        sandbox: z.string().url().describe("The sandbox it came from, which it is shared with once taken in."),
+    })
+    .strict();
+export type KeyringInboxItem = z.infer<typeof KeyringInboxItemSchema>;
+
+export const KeyringInboxResultSchema = z.discriminatedUnion("ok", [z.object({ ok: z.literal(true), pending: z.boolean().describe("Whether it waits for the next unlock.") }), refusal]);
+export type KeyringInboxResult = z.infer<typeof KeyringInboxResultSchema>;
+
+// `copy` entries, sealed to the asking sandbox's key, for the sandbox to keep as its own; asked for on connect and after
+// a change, so an edit on the computer reaches the copy.
+export const KeyringCopiesSchema = z.object({
+    copies: z.array(z.object({ name: KeyringSecretNameSchema, sealed: SealedBoxSchema, updatedAt: z.number() })),
+});
+export type KeyringCopies = z.infer<typeof KeyringCopiesSchema>;
+
+// ---- sync between the owner's computers ----
+
+// Keyrings on two of the owner's computers keep one set of entries by sealing each change to the other's sync key and
+// leaving it in a sandbox both link to, which carries only ciphertext and never a key that opens it. Two keyrings are
+// paired once, at a person's word on each computer, each showing both fingerprints to compare; a sandbox that swapped a
+// key would show a fingerprint the other screen does not.
+export const KeyringSyncPeerSchema = z.object({
+    device: z.string().min(1).max(128).describe("The other computer, by its device card."),
+    key: KeyringPublicKeySchema.describe("Its keyring's sync key."),
+    pairedAt: z.number().describe("When the two were paired, in milliseconds."),
+});
+export type KeyringSyncPeer = z.infer<typeof KeyringSyncPeerSchema>;
+
+export const KeyringSyncStateSchema = z.object({
+    key: KeyringPublicKeySchema.describe("This keyring's own sync key."),
+    peers: z.array(KeyringSyncPeerSchema).describe("The keyrings it keeps in step with."),
+    revision: z.number().int().nonnegative().describe("How many changes this keyring has made, for ordering what it sends."),
+});
+export type KeyringSyncState = z.infer<typeof KeyringSyncStateSchema>;
+
+export const KeyringSyncItemSchema = z
+    .object({
+        from: KeyringPublicKeySchema.describe("The sending keyring's sync key."),
+        to: KeyringPublicKeySchema.describe("The receiving keyring's sync key."),
+        revision: z.number().int().nonnegative(),
+        sealed: SealedBoxSchema.describe("The sender's entries, sealed to the receiver for `sync` with its own revision."),
+    })
+    .strict();
+export type KeyringSyncItem = z.infer<typeof KeyringSyncItemSchema>;
+
+export const KeyringSyncPairSchema = z
+    .object({
+        peer: z.object({ device: z.string().min(1).max(128), key: KeyringPublicKeySchema }).strict(),
+        // The device card this keyring's own computer is known by, so the prompt can name both.
+        self: z.string().min(1).max(128),
+    })
+    .strict();
+
+export const KeyringSyncPairResultSchema = z.discriminatedUnion("ok", [z.object({ ok: z.literal(true) }), refusal]);
+export const KeyringSyncOutboxSchema = z.object({ items: z.array(KeyringSyncItemSchema) });
+export const KeyringSyncDeliverSchema = z.object({ items: z.array(KeyringSyncItemSchema).max(64) }).strict();
+export const KeyringSyncDeliverResultSchema = z.object({ accepted: z.number().int().nonnegative().describe("How many it took; the rest were not from a paired keyring or did not open.") });