@intentic/sandbox-contract 1.337.0 → 1.338.0

package/src/schemas/organisation.ts

@@ -0,0 +1,110 @@
+import { z } from "zod";
+import { PRESET_GROUPS, type PresetGroup, PresetGroupSchema } from "./compliance.js";
+
+// An ORGANISATION'S POLICY as a sandbox holds it (docs/architecture/organisations.md). A sandbox that belongs to an
+// organisation is handed this by the platform it is registered with; a personal sandbox never holds one, and nothing
+// here applies to it. The daemon is the enforcing copy: a section the policy locks is refused at the daemon's own
+// middleware for every caller, the owner and the agent included, and the editor only draws what the daemon says.
+
+// The parts of a sandbox an organisation can take out of its members' hands. Each is a section of the editor's sandbox
+// hub (sandboxNav.ts) except `updates`, which is the auto-update switch on Overview. Which daemon routes each one
+// covers is policy/org-locks.ts, beside the refusal that reads it.
+export const ORG_SECTIONS = [
+    "models",
+    "agent",
+    "environment",
+    "secrets",
+    "data-protection",
+    "extensions",
+    "access",
+    "areas",
+    "personas",
+    "updates",
+] as const;
+export const OrgSectionSchema = z.enum(ORG_SECTIONS);
+export type OrgSection = z.infer<typeof OrgSectionSchema>;
+
+// `open`: as in a personal sandbox. `locked`: readable, every change refused. `hidden`: locked, and the editor does not
+// show the section at all. Hidden is a fence on what people are shown, not on what the sandbox reads: the agent still
+// uses the secrets of a hidden Secrets section, and a read route answers as it always did.
+export const OrgSectionModeSchema = z.enum(["open", "locked", "hidden"]);
+export type OrgSectionMode = z.infer<typeof OrgSectionModeSchema>;
+
+// What an organisation admin edits. A section left out is open, so a policy written before a section existed opens it
+// rather than guessing.
+//
+// `preset` PINS settings rather than locking a page: each named group of the public-office preset (compliance.ts
+// PRESET_GROUPS; which settings a group holds is the daemon's compliance/preset.ts) is applied to what the sandbox READS,
+// whatever its files say, and a change that would undo it is refused. Strings on the wire, not the enum: a group a newer
+// platform names and this daemon does not know is skipped and reported (`unenforced`), never a reason to refuse the
+// whole policy, which would stop every later edition reaching an older daemon. The platform validates the names an
+// admin saves.
+//
+// `membersOnly` makes the organisation's member list the outer fence of every bound sandbox's roster: a person the
+// organisation removes is taken off each sandbox's roster by its daemon at the next fetch, and a grant to someone who
+// is not a member is refused. The sandbox's owner is not on a roster, so this never reaches them.
+//
+// Both are optional rather than defaulted, so every policy written before them (a stored row, a held file, a literal)
+// still reads as the same type: absent is no pin and an open roster.
+export const OrgPolicyRulesSchema = z.object({
+    sections: z
+        .partialRecord(OrgSectionSchema, OrgSectionModeSchema)
+        .default({})
+        .describe("How each section is held. A section left out is open."),
+    preset: z
+        .array(z.string().min(1).max(40))
+        .max(40)
+        .optional()
+        .describe(`Public-office preset groups every bound sandbox is held to (${PRESET_GROUPS.join(", ")}). Unknown names are skipped.`),
+    membersOnly: z
+        .boolean()
+        .optional()
+        .describe("Only the organisation's members may be on a bound sandbox's roster; removing someone from the organisation removes them everywhere."),
+});
+export type OrgPolicyRules = z.infer<typeof OrgPolicyRulesSchema>;
+
+// The rules as one sandbox receives them: whose they are and which edition. `version` only grows on the platform; the
+// daemon reports the edition it holds back, which is how the organisation's console tells applied from pending.
+// `people` is computed by the platform, never edited: the organisation's members, each as the sha256 of
+// orgPersonPreimage, sent only while `membersOnly` is on, so a daemon can test an address without being handed the
+// staff list in clear. A policy with `membersOnly` and no `people` fences nothing: no list is not an empty list.
+export const OrgPolicySchema = OrgPolicyRulesSchema.extend({
+    orgId: z.string().min(1).max(64),
+    orgName: z.string().min(1).max(120),
+    version: z.number().int().min(1),
+    people: z.array(z.string().regex(/^[0-9a-f]{64}$/u)).max(10_000).optional(),
+});
+export type OrgPolicy = z.infer<typeof OrgPolicySchema>;
+
+// What the daemon answers the editor about it (GET /org/policy): unbound, or bound with the policy it enforces and
+// when it last heard from the platform about it. `provisional` is a held file that could not be read: every section is
+// held read-only until the platform answers, since a bound sandbox must not open up because its record broke.
+// `unenforced` names preset groups the policy pins that this daemon does not know.
+export const OrgPolicyStateSchema = z.discriminatedUnion("bound", [
+    z.object({ bound: z.literal(false) }),
+    z.object({
+        bound: z.literal(true),
+        policy: OrgPolicySchema,
+        receivedAt: z.string().describe("When this edition arrived (ISO)."),
+        provisional: z.boolean().optional(),
+        unenforced: z.array(z.string()).optional(),
+    }),
+]);
+export type OrgPolicyState = z.infer<typeof OrgPolicyStateSchema>;
+
+// How a policy holds one section; anything it does not name is open.
+export const orgSectionMode = (policy: Pick<OrgPolicy, "sections"> | undefined, section: OrgSection): OrgSectionMode =>
+    policy?.sections[section] ?? "open";
+
+// The preset groups a policy pins that this build knows, in the contract's order; none for a personal sandbox. A policy
+// stored before pins existed has no `preset` at all.
+export const orgPinnedGroups = (policy: Partial<Pick<OrgPolicy, "preset">> | undefined): PresetGroup[] =>
+    PRESET_GROUPS.filter((group) => policy?.preset?.includes(group) === true);
+
+// The names a policy pins that this build does not know.
+export const orgUnknownPins = (policy: Partial<Pick<OrgPolicy, "preset">> | undefined): string[] =>
+    (policy?.preset ?? []).filter((name) => !PresetGroupSchema.safeParse(name).success);
+
+// What both sides hash (sha256, hex) to name one member of one organisation in `people`: salted with the organisation's
+// id, so the same address in two organisations does not read as the same digest.
+export const orgPersonPreimage = (orgId: string, email: string): string => `intentic-org-person:${orgId}:${email.trim().toLowerCase()}`;

package/src/schemas/privacy.test.ts

@@ -0,0 +1,63 @@
+import { DEFAULT_PRIVACY_SHIELD, PRIVACY_PATTERN_MAX, PrivacyShieldPolicySchema, patternProblem } from "./privacy.js";
+
+// The owner's own patterns run on every string bound for an untrusted provider, in the daemon's one thread: one that
+// cannot compile, matches empty text or nests a repeat inside a repeat is refused before it is saved.
+
+describe(`patternProblem`, () => {
+    it(`takes the patterns an ID or a customer number is written with`, () => {
+        for (const pattern of [
+            String.raw`EMP-\d{6}`,
+            String.raw`\b[A-Z]{3}\d{6}\b`,
+            String.raw`Customer:\s*(?<value>\d+)`,
+            String.raw`(?:\d{3}-){2}\d{4}`,
+            String.raw`[A-Z]{2}\d{2}(?:[ -]?\d{4}){3}`,
+            String.raw`(?<=Ref\. )[A-Z0-9]+`,
+            String.raw`(ab|cd)+`,
+            String.raw`[(+*)]+x`,
+        ]) {
+            expect([pattern, patternProblem(pattern)]).toEqual([pattern, undefined]);
+        }
+    });
+
+    it(`refuses one that does not compile, matches empty text or is too long`, () => {
+        expect(patternProblem(`(unclosed`)).toBe(`invalid`);
+        expect(patternProblem(String.raw`\p{Nope}`)).toBe(`invalid`);
+        expect(patternProblem(String.raw`\d*`)).toBe(`empty`);
+        expect(patternProblem(`a|`)).toBe(`empty`);
+        expect(patternProblem(` `)).toBe(`empty`);
+        expect(patternProblem(`a`.repeat(PRIVACY_PATTERN_MAX + 1))).toBe(`tooLong`);
+    });
+
+    it(`refuses a variable repeat inside a variable repeat, the shape that backtracks for minutes`, () => {
+        expect(patternProblem(`(a+)+b`)).toBe(`nested`);
+        expect(patternProblem(String.raw`(\w+\s?)*!`)).toBe(`nested`);
+        expect(patternProblem(String.raw`(?:x(?:\d{2,})?)+y`)).toBe(`nested`);
+        expect(patternProblem(String.raw`(?<id>\d+-?){2,}z`)).toBe(`nested`);
+        // A fixed count is no variable repeat, inside or out.
+        expect(patternProblem(String.raw`(\d{3}-?){3}`)).toBeUndefined();
+        expect(patternProblem(String.raw`(\d{3}){2,}`)).toBeUndefined();
+    });
+});
+
+describe(`PrivacyShieldPolicySchema`, () => {
+    it(`reads a policy written before the owner's lists and rules as having none`, () => {
+        expect(PrivacyShieldPolicySchema.parse({ mode: `on` })).toMatchObject({ dictionary: { off: [], lists: [] }, rules: [] });
+        expect(DEFAULT_PRIVACY_SHIELD.rules).toEqual([]);
+    });
+
+    it(`fills a rule's defaults and keeps a stored pattern whatever a later build judges of it`, () => {
+        const parsed = PrivacyShieldPolicySchema.parse({
+            rules: [{ id: `r1`, title: `Nested`, class: `identity-document`, match: `pattern`, pattern: `(a+)+` }],
+        });
+        expect(parsed.rules[0]).toEqual({
+            id: `r1`,
+            title: `Nested`,
+            on: true,
+            class: `identity-document`,
+            match: `pattern`,
+            terms: [],
+            pattern: `(a+)+`,
+            matchCase: false,
+        });
+    });
+});

package/src/schemas/privacy.ts

@@ -44,6 +44,183 @@ export const PRIVACY_TRUSTED_MAX = 200;
 export const PRIVACY_ALLOW_MAX = 1000;
 export const PRIVACY_CONVERSATIONS_MAX = 200;
 
+// The owner's own additions to what the shield finds. The policy travels whole on every write, so each is kept to what a
+// person types or pastes; a dataset of thousands of values is taught to the vault instead (privacy learn).
+export const PRIVACY_OWN_LISTS_MAX = 20;
+export const PRIVACY_OWN_LIST_WORDS_MAX = 2000;
+export const PRIVACY_WORD_MAX = 60;
+export const PRIVACY_RULES_MAX = 50;
+export const PRIVACY_RULE_TERMS_MAX = 1000;
+export const PRIVACY_TERM_MAX = 200;
+export const PRIVACY_PATTERN_MAX = 500;
+export const PRIVACY_TITLE_MAX = 80;
+
+// What a word on a name list says about a name: a first name or a surname (a name when the two stand together), a word
+// that is a name only beside other evidence, a title after which a capitalized word is a person, or never part of one.
+export const PrivacyNameListKindSchema = z.enum(["first-name", "surname", "ambiguous", "title", "never"]);
+export type PrivacyNameListKind = z.infer<typeof PrivacyNameListKindSchema>;
+
+// inflected: every Polish grammatical form of a listed word ("Kasia", "Kasi", "Kasię"); as-written: only as listed.
+export const PrivacyNameMatchingSchema = z.enum(["inflected", "as-written"]);
+export type PrivacyNameMatching = z.infer<typeof PrivacyNameMatchingSchema>;
+
+// Ids the editor mints for the owner's lists and rules: stable across renames, so a write never confuses two of them.
+const OwnIdSchema = z.string().regex(/^[a-z0-9][a-z0-9-]{0,39}$/u);
+
+export const PrivacyOwnNameListSchema = z.object({
+    id: OwnIdSchema,
+    title: z.string().min(1).max(PRIVACY_TITLE_MAX),
+    kind: PrivacyNameListKindSchema,
+    matching: PrivacyNameMatchingSchema.default("as-written"),
+    words: z
+        .array(z.string().min(1).max(PRIVACY_WORD_MAX))
+        .max(PRIVACY_OWN_LIST_WORDS_MAX)
+        .default([])
+        .describe("One word each, in any case: the list is read as the built-in lists are."),
+    on: z.boolean().default(true),
+});
+export type PrivacyOwnNameList = z.infer<typeof PrivacyOwnNameListSchema>;
+
+export const PrivacyDictionaryPolicySchema = z.object({
+    off: z.array(z.string().min(1).max(64)).max(64).default([]).describe("Built-in name lists switched off, by id (privacy.dictionary names them)."),
+    lists: z
+        .array(PrivacyOwnNameListSchema)
+        .max(PRIVACY_OWN_LISTS_MAX)
+        .default([])
+        .describe("The owner's own name lists, read beside the built-in ones."),
+});
+export type PrivacyDictionaryPolicy = z.infer<typeof PrivacyDictionaryPolicySchema>;
+
+// One of the owner's own rules: what it matches is masked wherever it stands, with no context asked for, as the kind it
+// names. terms: each word or phrase as a whole word, in any case unless matchCase. pattern: a regular expression (with the
+// `u` flag, `i` unless matchCase); a group named `value` masks only that part of a match.
+export const PrivacyRuleMatchSchema = z.enum(["terms", "pattern"]);
+export type PrivacyRuleMatch = z.infer<typeof PrivacyRuleMatchSchema>;
+
+export const PrivacyRuleSchema = z.object({
+    id: OwnIdSchema,
+    title: z.string().min(1).max(PRIVACY_TITLE_MAX),
+    on: z.boolean().default(true),
+    class: PersonalDataClassSchema.describe("The kind what it matches is masked as; switching that kind off stops the rule too."),
+    match: PrivacyRuleMatchSchema,
+    terms: z.array(z.string().min(1).max(PRIVACY_TERM_MAX)).max(PRIVACY_RULE_TERMS_MAX).default([]),
+    // Only its size is held here: whether a pattern is safe to run is judged when it is saved (patternProblem), so a
+    // stored one never turns unreadable because a later build judges more strictly.
+    pattern: z.string().max(PRIVACY_PATTERN_MAX).default(""),
+    matchCase: z.boolean().default(false),
+});
+export type PrivacyRule = z.infer<typeof PrivacyRuleSchema>;
+
+// Why a pattern cannot be saved. Owner-written patterns run on every string bound for an untrusted provider, in the
+// daemon's one thread, so beside not compiling: one that matches empty text masks nothing and only costs, and a repeat
+// inside a repeat (`(a+)+`, `(\w+\s?)*`) can take minutes on one line that almost matches.
+export type PrivacyPatternProblem = "invalid" | "tooLong" | "empty" | "nested";
+
+// The length of a quantifier at `at`, and whether it repeats a variable number of times (`*`, `+`, `{2,}`, `{2,5}`); `?`
+// and `{3}` do not. A lazy `?` after it is part of it.
+const quantifierAt = (source: string, at: number): { readonly length: number; readonly varies: boolean } | undefined => {
+    const char = source[at];
+    let length: number;
+    let varies: boolean;
+    if (char === "*" || char === "+" || char === "?") {
+        length = 1;
+        varies = char !== "?";
+    } else if (char === "{") {
+        const braces = /^\{(\d+)(?:(,)(\d*))?\}/u.exec(source.slice(at));
+        if (braces === null) {
+            return undefined;
+        }
+        const [whole, min = "0", comma, max] = braces;
+        length = whole.length;
+        varies = comma !== undefined && (max === undefined || max === "" || Number(max) > Number(min));
+    } else {
+        return undefined;
+    }
+    return { length: source[at + length] === "?" ? length + 1 : length, varies };
+};
+
+// One step of the walk below: where the next one starts, and what this one was.
+interface PatternStep {
+    readonly next: number;
+    readonly kind: "open" | "close" | "repeat" | "other";
+}
+
+// Past a character class, escapes inside it included.
+const classEnd = (source: string, at: number): number => {
+    let end = at + 1;
+    while (end < source.length && source[end] !== "]") {
+        end += source[end] === "\\" ? 2 : 1;
+    }
+    return end + 1;
+};
+
+// Past a group's opening and its own prefix (`?:`, `?=`, `?<name>`), which is no quantifier.
+const groupStart = (source: string, at: number): number => {
+    if (source[at + 1] !== "?") {
+        return at + 1;
+    }
+    const name = /^\?<(?![=!])[^>]*>/u.exec(source.slice(at + 1));
+    return at + 1 + (name === null ? 2 : name[0].length);
+};
+
+const stepAt = (source: string, at: number): PatternStep => {
+    const char = source[at];
+    if (char === "\\") {
+        return { next: at + 2, kind: "other" };
+    }
+    if (char === "[") {
+        return { next: classEnd(source, at), kind: "other" };
+    }
+    if (char === "(") {
+        return { next: groupStart(source, at), kind: "open" };
+    }
+    if (char === ")") {
+        return { next: at + 1, kind: "close" };
+    }
+    const quantifier = quantifierAt(source, at);
+    return quantifier === undefined
+        ? { next: at + 1, kind: "other" }
+        : { next: at + quantifier.length, kind: quantifier.varies ? "repeat" : "other" };
+};
+
+// Whether a group that repeats a variable number of times holds such a repeat itself: a star height above one.
+const nestedRepeat = (source: string): boolean => {
+    // Per open group, whether something inside it repeats.
+    const open: boolean[] = [];
+    // Whether the step before was the close of a group that held a repeat.
+    let closedRepeating = false;
+    for (let at = 0; at < source.length;) {
+        const step = stepAt(source, at);
+        at = step.next;
+        if (step.kind === "open") {
+            open.push(false);
+        } else if (step.kind === "repeat") {
+            if (closedRepeating) {
+                return true;
+            }
+            open.fill(true);
+        }
+        closedRepeating = step.kind === "close" && (open.pop() ?? false);
+    }
+    return false;
+};
+
+export const patternProblem = (source: string): PrivacyPatternProblem | undefined => {
+    if (source.length > PRIVACY_PATTERN_MAX) {
+        return "tooLong";
+    }
+    let compiled: RegExp;
+    try {
+        compiled = new RegExp(source, "u");
+    } catch {
+        return "invalid";
+    }
+    if (source.trim() === "" || compiled.test("")) {
+        return "empty";
+    }
+    return nestedRepeat(source) ? "nested" : undefined;
+};
+
 // One conversation the owner let an untrusted provider read as it is, granted from that conversation's own composer:
 // narrower than the trusted list, and the way on for a provider whose runtime the gateway cannot sit in front of
 // (Cursor's own wire, an ACP agent, Pi), which the shield otherwise refuses outright.
@@ -78,6 +255,14 @@ export const PrivacyShieldPolicySchema = z.object({
         .max(PRIVACY_CONVERSATIONS_MAX)
         .default([])
         .describe("Providers that may read one conversation's personal data as it is, each granted from that conversation; oldest first."),
+    dictionary: PrivacyDictionaryPolicySchema.default({ off: [], lists: [] }).describe(
+        "The name dictionary as the owner adjusted it: built-in lists switched off, and lists of their own.",
+    ),
+    rules: z
+        .array(PrivacyRuleSchema)
+        .max(PRIVACY_RULES_MAX)
+        .default([])
+        .describe("The owner's own rules: words, phrases and patterns masked wherever they stand."),
 });
 export type PrivacyShieldPolicy = z.infer<typeof PrivacyShieldPolicySchema>;
 
@@ -204,18 +389,21 @@ export const PrivacyKnownSourceSchema = z.object({
 export type PrivacyKnownSource = z.infer<typeof PrivacyKnownSourceSchema>;
 
 // The name lists the shield finds names by when no model is asked for (and alongside one when it is): what each list
-// holds, how many, and where it came from.
+// holds, how many, and where it came from; the owner's own lists among them.
 export const PrivacyNameListSchema = z.object({
     id: z.string().describe("Stable id of the list."),
-    kind: z.enum(["first-name", "surname", "ambiguous", "title", "never"]).describe("What a word on it says about a name."),
+    kind: PrivacyNameListKindSchema.describe("What a word on it says about a name."),
     languages: z.array(z.enum(["pl", "en", "multi"])).describe("The languages its words come from; multi: many languages at once."),
     count: z.number().int().describe("How many words it holds."),
-    matching: z
-        .enum(["inflected", "as-written"])
-        .describe("inflected: matched in every grammatical form of a listed word; as-written: matched only exactly as listed."),
+    matching: PrivacyNameMatchingSchema.describe(
+        "inflected: matched in every grammatical form of a listed word; as-written: matched only exactly as listed.",
+    ),
     source: z.string().describe("Where the words come from: the register or dataset, or that they were written by hand."),
     url: z.string().optional().describe("The source's page, where it has one."),
     license: z.string().optional(),
+    on: z.boolean().describe("Read by the shield; the owner can switch any list off."),
+    own: z.boolean().optional().describe("One of the owner's own lists (policy.dictionary.lists), titled by them."),
+    title: z.string().optional().describe("An own list's title."),
 });
 export type PrivacyNameList = z.infer<typeof PrivacyNameListSchema>;
 
@@ -255,3 +443,23 @@ export const PrivacyDictionarySchema = z.object({
     lookup: PrivacyNameLookupSchema.optional(),
 });
 export type PrivacyDictionary = z.infer<typeof PrivacyDictionarySchema>;
+
+// What the shield would mask in a text the owner tries it on, with the policy as saved: where each find sits, its kind,
+// and what found it. Nothing is given a token and nothing is kept, so trying a value teaches the vault nothing.
+export const PRIVACY_PREVIEW_MAX = 4000;
+
+export const PrivacyPreviewSpanSchema = z.object({
+    start: z.number().int(),
+    end: z.number().int().describe("Exclusive."),
+    class: PersonalDataClassSchema,
+    by: z
+        .enum(["detector", "rule", "learned", "model"])
+        .describe(
+            "detector: the built-in detectors and name lists, the owner's lists included; rule: one of the owner's rules; learned: a value the vault knows; model: the local name model.",
+        ),
+    rule: z.string().optional().describe("The id of the owner's rule that found it."),
+});
+export type PrivacyPreviewSpan = z.infer<typeof PrivacyPreviewSpanSchema>;
+
+export const PrivacyPreviewSchema = z.object({ spans: z.array(PrivacyPreviewSpanSchema) });
+export type PrivacyPreview = z.infer<typeof PrivacyPreviewSchema>;

package/src/schemas/secrets.ts

@@ -1,6 +1,7 @@
 // secrets: user-supplied env-var secrets the daemon writes to desired-state/.env
 import { BrokerRuleSchema } from "@intentic/extension-manifest";
 import { z } from "zod";
+import { KEYRING_PROGRAMS_MAX, KeyringPackageSchema, KeyringProgramSchema, KeyringShareModeSchema, KeyringSourceSchema } from "./keyring.js";
 import { SECRET_HOST_MAX, SECRET_HOST_PATTERN_RE, SECRET_HOSTS_MAX } from "../policy/secret-hosts.js";
 // Straight to the sandbox daemon, never through the platform; `apply` reloads .env with no restart. `list` returns keys
 // only; `reveal` is the one owner-only exception that returns a value.
@@ -61,9 +62,9 @@ export const CredentialGateKindSchema = z
 export type CredentialGateKind = z.infer<typeof CredentialGateKindSchema>;
 
 export const CredentialLaneSchema = z
-    .enum(["shell", "code", "browser", "session", "otp", "gateway", "ssh"])
+    .enum(["shell", "code", "browser", "session", "otp", "gateway", "ssh", "device", "desktop"])
     .describe(
-        "What the credential was about to be used for: a shell command, a script, typing into a page, mounting a connected account, one one-time code, a request the credential gateway attaches it to, or a signature the sandbox's ssh agent makes with a held key.",
+        "What the credential was about to be used for: a shell command, a script, typing into a page, mounting a connected account, one one-time code, a request the credential gateway attaches it to, a signature the sandbox's ssh agent makes with a held key, typing into a window or phone app on one of the owner's computers, or typing into a window on the sandbox's own desktop.",
     );
 export type CredentialLane = z.infer<typeof CredentialLaneSchema>;
 
@@ -121,9 +122,9 @@ export const SecretHostSchema = z
     );
 
 export const SecretHostSourceSchema = z
-    .enum(["owner", "connector"])
+    .enum(["owner", "connector", "keyring"])
     .describe(
-        "Who set it: the owner, or the connector the credential belongs to, whose guard is on with its own service's hosts until the owner changes it.",
+        "Who set it: the owner, the connector the credential belongs to (whose guard is on with its own service's hosts until the owner changes it), or the keyring on the computer that holds the secret, whose list is changed there.",
     );
 export type SecretHostSource = z.infer<typeof SecretHostSourceSchema>;
 
@@ -208,12 +209,84 @@ export const CredentialPolicySetSchema = z.object({
 });
 export type CredentialPolicySet = z.infer<typeof CredentialPolicySetSchema>;
 
+// The program guard: the host guard's counterpart for typing into windows. A sandbox-held secret typed into a window on
+// one of the owner's computers goes unasked only into a program on its list and, unless `anyField`, only into a field the
+// program marks as a password field; anywhere else it waits for a person. A keyring entry carries its own list, kept on
+// that computer (schemas/keyring.ts), which the sandbox can show and never widen.
+export const SecretProgramsSchema = z.object({
+    programs: z.array(KeyringProgramSchema).max(KEYRING_PROGRAMS_MAX).describe("Programs, by executable name or whole path, it may be typed into unasked."),
+    packages: z.array(KeyringPackageSchema).max(KEYRING_PROGRAMS_MAX).describe("Android apps, by package name, it may be typed into unasked."),
+    anyField: z.boolean().describe("Whether it may go into a field not marked as a password field without asking."),
+    source: z.enum(["owner", "keyring"]).describe("Who keeps the list: the owner, here, or the keyring on the computer that holds the secret."),
+});
+export type SecretPrograms = z.infer<typeof SecretProgramsSchema>;
+
+export const SecretProgramGuardSchema = SecretProgramsSchema.omit({ source: true }).extend({
+    subject: z.string().min(1).describe("Which secret, by the name its reference carries."),
+});
+export type SecretProgramGuard = z.infer<typeof SecretProgramGuardSchema>;
+
+export const SecretProgramGuardsSchema = z.object({
+    guards: z.array(SecretProgramGuardSchema).describe("Every sandbox-held secret whose program list has been set. Names and programs only, never a value."),
+});
+
+export const SecretProgramGuardSetSchema = SecretProgramGuardSchema.extend({
+    conversationId: z.string().optional().describe("Which conversation to ask the owner in, when the change needs them. The CLI fills this from the running turn."),
+});
+
+export const SecretProgramGuardSetResultSchema = SecretProgramsSchema.omit({ source: true }).extend({
+    approvedBy: z.string().optional().describe("Who approved the change, when it needed the owner's click. Absent when nobody had to."),
+});
+
+// The owner's Type into…: one secret typed into whatever has focus on one of their computers, after a countdown that
+// leaves time to put the cursor there. Through that computer's keyring, which still asks when its entry's mode says to.
+export const SecretTypeIntoSchema = z.object({
+    key: secretKey.describe("Which secret, by name."),
+    device: z.string().min(1).describe("Which computer, by its device card (`rog`, or `rog::wsl:archlinux` for a distro's own keyring)."),
+    countdownSeconds: z.number().int().min(0).max(10).default(3).describe("How long to wait before typing, for the cursor to be put in place."),
+});
+export const SecretTypeIntoResultSchema = z.object({
+    program: z.string().describe("What it was typed into."),
+    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."),
+});
+
+// The keyrings on the owner's computers this sandbox can reach: where a secret can be kept or typed, and which two can be
+// paired to keep one set of entries.
+export const SandboxKeyringSchema = z.object({
+    machine: z.string().describe("The computer, by its device card."),
+    online: z.boolean().describe("Whether it answers now."),
+    locked: z.boolean().optional().describe("Whether its keyring is locked, as last heard. Absent while offline."),
+    version: z.string().optional().describe("The keyring's release, as last heard."),
+    pendingInbox: z.number().int().nonnegative().optional().describe("Values sent to be kept there that wait for its next unlock."),
+    shared: z.number().int().nonnegative().describe("How many of its entries are shared with this sandbox."),
+    sync: z
+        .object({
+            fingerprint: z.string().describe("Its sync key's fingerprint, to compare with what the other computer shows when pairing."),
+            peers: z.array(z.string()).describe("The computers it is paired with, by device card."),
+        })
+        .optional()
+        .describe("Its pairing with the owner's other keyrings. Absent while offline or before it was heard."),
+});
+export type SandboxKeyring = z.infer<typeof SandboxKeyringSchema>;
+export const SandboxKeyringsSchema = z.object({ keyrings: z.array(SandboxKeyringSchema) });
+
+export const SandboxKeyringPairSchema = z.object({
+    a: z.string().min(1).describe("One computer, by its device card."),
+    b: z.string().min(1).describe("The other."),
+});
+export const SandboxKeyringPairResultSchema = z.object({
+    fingerprints: z.object({ a: z.string(), b: z.string() }).describe("Each keyring's sync-key fingerprint, as both prompts showed them."),
+});
+
 export const SecretInventoryEntrySchema = z.object({
     // Env-var key for env|generated; `<provider>:<accountId>` for provider; capability instance id otherwise.
     key: z.string().describe("What identifies it. Unique across the whole inventory, so several accounts of one provider each get their own entry."),
     kind: z
-        .enum(["env", "generated", "capability", "provider"])
-        .describe("Where it came from: you set it, the sandbox generated it, a connection needs it, or it is a model account's credential."),
+        .enum(["env", "generated", "capability", "provider", "device"])
+        .describe(
+            "Where it came from: you set it, the sandbox generated it, a connection needs it, it is a model account's credential, or it lives in the keyring on one of your computers and this sandbox holds only a pointer to it.",
+        ),
     // e.g. "<ProviderName> · <accountLabel>" for provider entries; absent on env/generated.
     label: z.string().optional().describe("A friendlier name, for entries that have one."),
     status: z.enum(["missing", "set", "connected"]).describe("Whether it exists and, for a connection, whether it is working."),
@@ -237,9 +310,9 @@ export const SecretInventoryEntrySchema = z.object({
         .object({
             at: z.number().describe("When, in milliseconds."),
             lane: z
-                .enum(["shell", "code", "browser", "gateway", "ssh"])
+                .enum(["shell", "code", "browser", "gateway", "ssh", "device", "desktop"])
                 .describe(
-                    "How it was used: a command, a script, typed into a page, attached by the credential gateway to a request the agent sent, or a key the sandbox's ssh agent signed with for the agent.",
+                    "How it was used: a command, a script, typed into a page, attached by the credential gateway to a request the agent sent, a key the sandbox's ssh agent signed with for the agent, typed into a window or app on one of the owner's computers, or typed into a window on the sandbox's desktop.",
                 ),
             detail: z
                 .string()
@@ -272,6 +345,21 @@ export const SecretInventoryEntrySchema = z.object({
         })
         .optional()
         .describe("Its host guard. Absent when none was ever set and no connector sets one: the guard is off."),
+    // Joined from the program guards: which windows and phone apps a use may type it into unasked.
+    programs: SecretProgramsSchema.optional().describe(
+        "Which programs on the owner's computers, and which phone apps, it may be typed into without asking. Absent when none was set: typing it into any window asks first.",
+    ),
+    // A device row only: the keyring entry the pointer names. Everything here is the keyring's to change, on that computer.
+    device: z
+        .object({
+            machine: z.string().describe("Which computer's keyring holds it, by its device card."),
+            mode: KeyringShareModeSchema,
+            online: z.boolean().describe("Whether that computer answers now. Offline, an `each-use` or `while-here` secret cannot be used until it does."),
+            locked: z.boolean().optional().describe("Whether the keyring there is locked, as last heard. Absent while the computer is offline."),
+            source: KeyringSourceSchema,
+        })
+        .optional()
+        .describe("Where a secret held on one of your computers lives and how it is shared. Present on `device` rows only."),
 });
 export type SecretInventoryEntry = z.infer<typeof SecretInventoryEntrySchema>;
 export const SecretInventorySchema = z.object({

package/src/schemas/settings.ts

@@ -298,6 +298,14 @@ export const SandboxSettingsSchema = z.object({
         .describe(
             "Let the agent answer with a page drawn right in the chat: a chart, a table, a diagram, a mock-up, or a small form you answer it on. Off, the agent is not offered the tools at all, so it spends nothing on them.",
         ),
+    // The daemon's shadow keeper (derived/shadow-keeper.ts) and the ripgrep config agents' shells get with it. On by
+    // default: it renders without asking any model (OCR excepted, on this machine), one low-priority process at a time.
+    documentSearch: z
+        .boolean()
+        .default(true)
+        .describe(
+            "Keep the text of every document in the workspace (pdf, Word, OpenDocument, spreadsheets, presentations, epub, and scans where OCR is installed) ready to search. In the background, one low-priority process at a time, each document is rendered to text when it appears or changes, so `rg` and iq find what documents say under their own paths, cited by page. Off, nothing renders until someone opens a document, and searches skip them.",
+        ),
     hashlineEdits: z
         .boolean()
         .default(false)

package/src/schemas/speech.ts

@@ -74,7 +74,9 @@ export type SpeechTranscript = z.infer<typeof SpeechTranscriptSchema>;
 // streams each one as it is spoken. A text frame `begin` opens phrase `id`; binary frames that follow are its audio,
 // 16 kHz mono s16le; `end` closes it, keeping its first `keep` samples (the trailing pause trimmed off); `drop`
 // abandons it. The daemon answers with `partial` text while the phrase is still being spoken, one `final` per ended
-// phrase, in order, and `status` whenever the model's readiness moves. The language is the socket's `lang` query.
+// phrase, in order, and `status` whenever the model's readiness moves. The language is the socket's `lang` query;
+// `guesses=0` asks for finals alone, which the wake listener does: nobody reads a running guess at a room's talk, and
+// each one is a decode.
 export const SpeechClientMessageSchema = z.discriminatedUnion("type", [
     z.object({ type: z.literal("begin"), id: z.number() }),
     z.object({ type: z.literal("end"), id: z.number(), keep: z.number() }),
@@ -98,3 +100,38 @@ export type SpeechServerMessage = z.infer<typeof SpeechServerMessageSchema>;
 // The longest phrase either door takes: a minute at 16 kHz. The composer's segmenter cuts a monologue at the same
 // length, so nothing it sends is ever refused.
 export const MAX_SPEECH_SAMPLES = 60 * 16_000;
+
+// THE WAKE WORD: what a person says to the editor across the room to be heard without touching it ("Leon, fix the
+// build"). The editor listens for it on a device the person switched it on for, and hears it with this sandbox's own
+// model, so it is a word the model writes down: letters (any script), with a space, hyphen or apostrophe between them.
+export const WAKE_WORD_DEFAULT = "Leon";
+export const WakeWordSchema = z
+    .string()
+    .trim()
+    .regex(/^[\p{L}\p{M}](?:[\p{L}\p{M}' -]{0,38}[\p{L}\p{M}])?$/u)
+    .refine((word) => [...word].length >= 2, { message: "a wake word has at least two letters" });
+
+// POST /speech/wake: one device's claim on a wake it just heard. Every device listening for the same person hears the
+// same "Leon", and each would open its own session; the first to claim within a few seconds is granted it and the rest
+// stand down. A device keeps its own claims, so its next wake a moment later is never refused by its last one, and a
+// device in the middle of an exchange holds it longer, so a follow-up the other devices also hear stays with it.
+export const WAKE_HOLD_MAX_MS = 10 * 60_000;
+export const SpeechWakeClaimSchema = z.object({
+    device: z
+        .string()
+        .regex(/^[A-Za-z0-9_-]{8,64}$/u)
+        .describe("A random id this browser or app minted for itself once, so its own claims are told from another device's."),
+    holdMs: z
+        .number()
+        .int()
+        .min(0)
+        .max(WAKE_HOLD_MAX_MS)
+        .optional()
+        .describe("Keep the person's other devices off for this long rather than the few seconds a lone wake holds: an exchange this device is in the middle of."),
+});
+export type SpeechWakeClaim = z.infer<typeof SpeechWakeClaimSchema>;
+
+export const SpeechWakeGrantSchema = z.object({
+    granted: z.boolean().describe("This device acts on the wake; false when another device of the same person claimed it first."),
+});
+export type SpeechWakeGrant = z.infer<typeof SpeechWakeGrantSchema>;