@intentic/sandbox-contract 1.344.0 → 1.345.0

package/src/schemas/agents.ts

@@ -1,13 +1,14 @@
 // agents: the conversation fleet
 import { LandingDeliverySchema } from "./project-delivery.js";
 import { z } from "zod";
-import { AgentHarnessSchema, AgentOriginSchema, AgentProviderSchema, ConversationQueueSchema, ForkedFromSchema } from "./agent.js";
+import { AgentHarnessSchema, AgentOriginSchema, AgentProviderSchema, ConversationQueueSchema, ForkedFromSchema, FreshSessionSchema } from "./agent.js";
 import { LoopStateSchema } from "./loops.js";
 import { LimitPolicySchema, RetryPolicySchema, RoomPolicySchema, TurnBreakPolicySchema, TurnBreakSchema } from "./turn-break.js";
 import { KeepWarmSchema } from "./keep-warm.js";
 import { AgentNeedSchema } from "./needs.js";
 import { EMOJI_MAX_LENGTH, isSingleEmoji } from "../text/emoji.js";
 import { ProgramAskSchema } from "../events/requests.js";
+import { ReviewTallySchema, TurnProofSchema } from "./work-assurance.js";
 // A fleet agent is any conversation with a registry entry, keyed by conversationId. Isolated ones own a git worktree
 // (branch agent/<id>); workspace conversations have none, but both share one status/activity/cost lifecycle.
 
@@ -62,8 +63,7 @@ export const AgentAttentionSchema = z.object({
     // A missing capability on a card from before needs (docs/architecture/needs.md); lets the lane say "setup needed" rather than a generic
     // pause.
     capability: z.boolean().describe("It needs something connected that is not connected yet."),
-    // A gated credential parked on a named person's click; the one pause the board's reader may not be able to clear
-    // themselves.
+    // A gated credential parked on a named person's click; the one pause the board's reader may not be able to clear themselves.
     credential: z
         .boolean()
         .describe("It is waiting for a named person to release a credential. The one pause that may not be yours to clear, whatever your role."),
@@ -101,22 +101,8 @@ export const UnfinishedWorkSchema = z.object({
         ),
 });
 export type UnfinishedWork = z.infer<typeof UnfinishedWorkSchema>;
-// What the last turn showed of its own work, read off its tool calls and never asked of the model: the record a card
-// badges instead of sending the turn back to prove anything. CI checks what the owner pushes (schemas/ci.ts).
-export const TurnProofSchema = z.object({
-    at: z.number().describe("When the turn that left this ended, in milliseconds."),
-    verification: z
-        .enum(["verified", "unproven", "failing", "no-code"])
-        .describe(
-            "Verified: a check it ran passed after its last edit to code. Failing: the last one it ran failed. Unproven: it changed code and ran nothing that checked it. No-code: it changed nothing a check could speak to.",
-        ),
-    check: z.string().optional().describe("The command that spoke, when one did, so a targeted test is never read as the whole suite."),
-    unviewed: z
-        .number()
-        .optional()
-        .describe("How many rendered files it changed (pages, components, styles) without looking at the result afterwards. Absent when none."),
-});
-export type TurnProof = z.infer<typeof TurnProofSchema>;
+// What has looked at a conversation's work (its last turn's own checks, its latest code review): work-assurance.ts.
+export * from "./work-assurance.js";
 // How many entries each of a reach's lists carries; past it, the list's `…More` count says how many were left out.
 export const TURN_REACH_LIST_MAX = 10;
 // Where the last turn's work went when it went somewhere other than its own branch, read off what the turn touched and
@@ -175,8 +161,7 @@ export type TurnReach = z.infer<typeof TurnReachSchema>;
 // A landing's commit message: subject plus the two trailer sentences a changelog repo gets. One schema, not three
 // duplicated fields, since both the live roster and the review carrier must read the same shape and can't disagree.
 export const LandedMessageSchema = z.object({
-    // Written from the landed diff, not the opening prompt: a session that drifts from its title still needs an
-    // accurate subject.
+    // Written from the landed diff, not the opening prompt: a session that drifts from its title still needs an accurate subject.
     subject: z
         .string()
         .describe(
@@ -189,8 +174,7 @@ export const LandedMessageSchema = z.object({
         .describe(
             "The same change said to somebody who uses the product, for a repository that keeps a changelog. Usually absent, because most changes are not ones a user would notice.",
         ),
-    // Nearly always absent (removals only); required and mechanically guaranteed when a landing shrinks a wire-contract
-    // lock.
+    // Nearly always absent (removals only); required and mechanically guaranteed when a landing shrinks a wire-contract lock.
     breaking: z
         .string()
         .optional()
@@ -220,8 +204,7 @@ export const LandedMessageStepSchema = z.object({
     status: z
         .enum(["asking", "answered", "refused", "skipped"])
         .describe("How this one went. Skipped means it was not asked at all, because it refused a few minutes ago and the walk stepped over it."),
-    // Epoch ms it started; client-measures an in-flight step's ticking display. Absent for `skipped`, which cost no
-    // time.
+    // Epoch ms it started; client-measures an in-flight step's ticking display. Absent for `skipped`, which cost no time.
     at: z.number().optional().describe("When it started being asked, in milliseconds. Absent for one that was skipped, which cost no time."),
     ms: z.number().optional().describe("How long it took. Absent while it is still being asked."),
     reason: z.string().optional().describe("Why it refused, in its own words."),
@@ -297,16 +280,14 @@ export const AgentSummarySchema = z.object({
     status: AgentStatusSchema.describe(
         "What it is doing. Stopping and stopped are the two halves of somebody pressing stop, because a cancel is not instant; dismissing is the same window for a question waved away, which ends the turn too but owes the user nothing; resuming means the sandbox is already putting right whatever killed the turn; landing means its work is being carried into the workspace right now, and nothing may act on its branch until that settles.",
     ),
-    // Sentence the last turn died on; carried since `error` status alone isn't an answer, especially for an unwatched
-    // run.
+    // Sentence the last turn died on; carried since `error` status alone isn't an answer, especially for an unwatched run.
     failure: z
         .string()
         .optional()
         .describe(
             "Why the last turn failed, in the words it died on. Absent unless it did, and cleared the moment it runs again. Carried here because the word error on its own is not an answer, least of all for a run nobody was watching.",
         ),
-    // The error frame's own code, so the board can distinguish e.g. a rate limit from a crash the way chat already
-    // does.
+    // The error frame's own code, so the board can distinguish e.g. a rate limit from a crash the way chat already does.
     failureCode: z
         .string()
         .optional()
@@ -316,12 +297,18 @@ export const AgentSummarySchema = z.object({
     // Epoch seconds the spent allowance reopens; absent means genuinely unknown (Grok, Cursor) — never guess one.
     limitResetsAt: z.number().optional().describe("When the spent allowance reopens, in epoch seconds. Absent when the provider publishes no instant."),
     limitHeld: z.boolean().optional().describe("Whether the refused turn is held whole, so sending again re-runs it instead of appending to it."),
-    // Whether the daemon has already booked a retry at the reset; the one thing that keeps a stranded card out of the
-    // Attention lane.
+    // Whether the daemon has already booked a retry at the reset; the one thing that keeps a stranded card out of the Attention lane.
     limitScheduled: z.boolean().optional().describe("Whether the held turn is already booked to go again at the reset, so nobody has to press anything."),
-    // Account a booked move is sending the held turn to; set alongside `limitScheduled`, cleared by the move's own
-    // turn.
+    // Account a booked move is sending the held turn to; set alongside `limitScheduled`, cleared by the move's own turn.
     limitMoving: z.string().optional().describe("The account the held turn is being moved to by the owner's policy, while that move is booked."),
+    // The resume pass's own instant for the booked re-run, the one it fires by (limit-due.ts), so a card states when it
+    // goes rather than inferring it from the reset: they differ once the account it goes on is still spent at the reset.
+    limitNextAt: z
+        .number()
+        .optional()
+        .describe(
+            "When the held turn goes again by itself, in epoch seconds, while it is booked to (limitScheduled): later than the reset where the account it goes on is still spent, and already past for a booked move, which goes on the next pass. Absent while only a press sends it.",
+        ),
     provider: AgentProviderSchema.describe("Which model provider it runs on."),
     harness: AgentHarnessSchema.describe("Which agentic loop it runs on."),
     // Latched with the conversation, so the card can say where work runs without asking anything else.
@@ -414,6 +401,10 @@ export const AgentSummarySchema = z.object({
     forkedFrom: ForkedFromSchema.optional().describe(
         "The conversation this one was cut from. Recorded once and never cleared: it is the relationship, not a pending state.",
     ),
+    // Recorded once on a fresh session's first turn and never cleared; `startedBy` names the same origin as its parent.
+    fresh: FreshSessionSchema.optional().describe(
+        "Set on a conversation started on another conversation's work without its messages (a code review, a test pass, a person's own ask): which one, for what, and when. Absent for every other conversation.",
+    ),
     // Root repo's short base sha; per-repo bases stay daemon-internal.
     base: z.string().optional().describe("The commit its private copy started from, shortened."),
     costUsd: z.number().optional().describe("What it has cost so far, in dollars. A subagent's spend is its own and is not folded in here."),
@@ -543,6 +534,10 @@ export const AgentSummarySchema = z.object({
     proof: TurnProofSchema.optional().describe(
         "What its last turn showed of its work: whether a check it ran passed after its last edit, and whether it looked at interface files it changed. Absent until a turn that edited or checked anything has ended.",
     ),
+    // Written by the settle of the turn that reported a review, from its review frames; never asked of the model.
+    review: ReviewTallySchema.optional().describe(
+        "The latest code review this conversation reported: how many findings, and how many are still open. Absent until one has.",
+    ),
     // Written by the turn's own settle from its tool calls and a read of the clones and installs it could have touched;
     // replaced by every turn, so it says where the LAST turn's work went.
     reach: TurnReachSchema.optional().describe(
@@ -750,6 +745,19 @@ export const AgentTranscriptQuerySchema = AgentIdSchema.extend({
         .optional()
         .describe("Return the messages before this position in the record: the `from` of the page below. Absent asks for the most recent turns."),
     turns: z.coerce.number().int().min(1).max(200).optional().describe("How many of the user's turns to return, newest first. Absent takes the daemon's default."),
+    // Reading forward from the reader's cursor, checked by the row it names: a rewind since reuses positions.
+    after: z.coerce
+        .number()
+        .int()
+        .nonnegative()
+        .optional()
+        .describe(
+            "Return what the record holds from this position on: the `through` of the reader's last page. Answered `continuous` when it still runs through there; otherwise with its latest page. Ignored beside `before`.",
+        ),
+    afterRow: z
+        .string()
+        .optional()
+        .describe("The `rowId` of the row just before `after`, as the reader holds it: how a record rewound since is told apart from one that only grew."),
 });
 
 // Fills in what a page counted instead of carrying: a delegation's own calls, addressed by the card's id, which is
@@ -871,19 +879,6 @@ export const AgentReactSchema = z.object({
         .describe("The mark to leave, as the emoji character itself. Exactly one: a chip has room for one mark, and a press is one press."),
     on: z.boolean().describe("Whether to add your mark or take it back. Saying what you want rather than flipping what is there, so pressing twice lands where pressing once did."),
 });
-// Bounded just above the handoff's per-message render cap, so a line too long to carry whole doesn't reach the agent
-// truncated.
-export const AgentPlaceSchema = z.object({
-    id: z.string().min(1).describe("Which conversation."),
-    text: z
-        .string()
-        .trim()
-        .min(1)
-        .max(8_000)
-        .describe(
-            "The words to put in the agent's mouth. Bounded just above what the next turn can carry whole, because a line too long to be handed over intact would reach the agent truncated and quietly break the very thing this is for.",
-        ),
-});
 // `null` clears the override back to inheriting the sandbox setting, so an agent doesn't hold a frozen copy that stops
 // following it.
 export const AgentAutoLandSchema = z.object({

package/src/schemas/attach.ts

@@ -0,0 +1,23 @@
+import { z } from "zod";
+import { ConversationIdSchema } from "./agent.js";
+
+// Attaches to a conversation's newest run (live, or finished within retention); no cursor to resume from, the head
+// carries all rows. `run` names what the client was watching, so a newer run's head id tells it to catch up.
+export const AttachTurnSchema = z.object({
+    conversationId: ConversationIdSchema.describe("Which conversation to watch."),
+    run: z
+        .string()
+        .optional()
+        .describe(
+            "The run you were watching. The stream opens on the conversation's newest run whatever you name: if a newer turn has started since, the head names that one instead, and its rows are that turn's.",
+        ),
+    // The next run after one the reader saw end, which the conversation's queue starts a moment after: waited for here,
+    // where the start is an event, rather than looked for by a client asking again on a timer.
+    after: z
+        .string()
+        .optional()
+        .describe(
+            "A run you already watched to its end. The stream opens on the first run after it, waiting a few seconds for one to start (the message the conversation's queue sends next) before answering that nothing runs.",
+        ),
+});
+export type AttachTurn = z.infer<typeof AttachTurnSchema>;

package/src/schemas/command-admission.ts

@@ -0,0 +1,57 @@
+import { z } from "zod";
+
+// The class of thing asking to start a session, the admission policy's key space; derived daemon-side, never sent by a
+// client. Chat and loops are absent since both begin with the owner's own click.
+export const WakeSourceSchema = z.enum(["schedule", "event", "listener", "webchat", "issues", "workspace", "workflow"]);
+export type WakeSource = z.infer<typeof WakeSourceSchema>;
+// One admission verdict the owner can configure: let it run, hold it for approval, or refuse it outright.
+export const AdmissionRuleSchema = z.enum(["allow", "hold", "deny"]);
+export type AdmissionRule = z.infer<typeof AdmissionRuleSchema>;
+// Where a command would run; the same string means different things on each machine (rm -rf /usr is recoverable here,
+// fatal on a laptop). Read with a locus (command-classes.ts CommandContext); callers must state one rather than
+// default.
+export const CommandLocusSchema = z.enum([
+    // This sandbox's own shell: a disposable container, /work a git worktree, /history every other agent's.
+    "sandbox",
+    // One of the owner's own computers, reached through the machine agent. Nothing here is disposable.
+    "device",
+]);
+export type CommandLocus = z.infer<typeof CommandLocusSchema>;
+// What kind of thing a shell command is, the command gate's key space under the admission floor; gates one command
+// inside an already-running session. Six classes, chosen because each is hard or impossible to undo somewhere.
+export const CommandClassSchema = z.enum([
+    // Rewrites or discards committed work: force-push, hard reset, force-delete a branch, clean -f, filter-branch.
+    "git.destructive",
+    // Moves a checkout to another branch. Only ever matches in a tree the conversation SHARES with its owner: inside
+    // its own copy a conversation may stand where it likes, and the drift that causes is reported, not refused.
+    "git.branch-switch",
+    // Recursive-force deletion (`rm -rf`), and its spelling in a script (`fs.rm(p, { recursive: true })`).
+    "files.destructive",
+    // State nothing recovers at this locus; which roots count (/, /history in the sandbox) depends on the locus.
+    "system.destructive",
+    // A container volume or its data; the sandbox's blast radius (nested engine) differs sharply from a device's.
+    "container.state",
+    // Reads credential material: a secret reference, or a file confirmed to actually hold one.
+    "secrets.access",
+    // Publishes outward and irreversibly: npm/pnpm/yarn/cargo publish, gh release create, docker push.
+    "package.publish",
+    // A network program (curl, nc, ssh, scp, …) or interpreter one-liner aimed at a non-loopback or run-time-built
+    // destination, the general exfiltration channel under the per-provider actionRules.
+    "network.outbound",
+]);
+export type CommandClass = z.infer<typeof CommandClassSchema>;
+// Workspace-wide admission floor per wake source, consulted on every outside-driven wake; composes with per-automation
+// overrides most-restrictive-wins. `workflow` is allow|deny only, since a hold there is indistinguishable from a CI
+// runner's timeout.
+export const AdmissionPolicySchema = z.object({
+    schedule: AdmissionRuleSchema.default("allow"),
+    event: AdmissionRuleSchema.default("allow"),
+    listener: AdmissionRuleSchema.default("allow"),
+    webchat: AdmissionRuleSchema.default("allow"),
+    // Defaults to hold, unlike the others: a bug-report wake has full repo powers and a stranger's stack trace as its
+    // brief.
+    issues: AdmissionRuleSchema.default("hold"),
+    workspace: AdmissionRuleSchema.default("allow"),
+    workflow: z.enum(["allow", "deny"]).default("allow"),
+});
+export type AdmissionPolicy = z.infer<typeof AdmissionPolicySchema>;

package/src/schemas/conversation-links.ts

@@ -0,0 +1,62 @@
+import { z } from "zod";
+import { CONVERSATION_ID } from "../ids/conversation-ids.js";
+
+// HOW ONE CONVERSATION RELATES TO ANOTHER at its birth, latched on its registry entry and carried on its card: the
+// conversation a fork was cut from, and the work a fresh session was opened on. Re-exported by agent.ts, whose turn
+// names them on a conversation's first turn.
+
+// agent.ts's ConversationIdSchema, spelled here rather than imported, since agent.ts re-exports this module.
+const ConversationIdSchema = z.string().regex(CONVERSATION_ID);
+
+// Where a conversation was cut from, the durable half of a fork, carried on the registry entry. `index` is the message
+// the cut sat above in the source, so its transcript can put the mark back.
+export const ForkedFromSchema = z.object({
+    conversationId: ConversationIdSchema,
+    index: z.number().int().nonnegative(),
+    // Which files this fork opened on; kept so the fork can still say it later, not only right after the click.
+    files: z.enum(["then", "now"]),
+});
+export type ForkedFrom = z.infer<typeof ForkedFromSchema>;
+// A FRESH SESSION on another conversation's work: a code review, a test pass, or a person's own ask, started from that
+// conversation's work as it stands now and with none of its messages. A harness's own reviewer runs this way (Claude
+// Code's /code-review in a forked subagent, Codex's /review in a thread of its own) so it judges the diff rather than
+// the reasoning that produced it. Its first turn names the origin; the daemon then treats it as the origin's child: cut
+// from its current work, its edits going back into it, folded under its card. It is still a person's chat, never woken
+// for nor waking its origin: findings reach the origin only when a person sends them.
+export const FRESH_KINDS = ["review", "test", "ask"] as const;
+export const FreshKindSchema = z.enum(FRESH_KINDS);
+export type FreshKind = z.infer<typeof FreshKindSchema>;
+export const FreshOfSchema = z.object({
+    conversationId: ConversationIdSchema.describe("The conversation whose work this one starts from."),
+    kind: FreshKindSchema.describe("What it is opened for: a code review, a test pass, or the person's own ask."),
+});
+export type FreshOf = z.infer<typeof FreshOfSchema>;
+// The durable half, latched on the entry by the first turn and never cleared: the relationship, not a pending state.
+export const FreshSessionSchema = z.object({
+    of: ConversationIdSchema.describe("The conversation whose work it started from."),
+    kind: FreshKindSchema.describe("What it was opened for: a code review, a test pass, or the person's own ask."),
+    at: z.number().describe("When it started, in milliseconds. Work its origin changed after this is work it has not seen."),
+});
+export type FreshSession = z.infer<typeof FreshSessionSchema>;
+
+export const FRESH_OF_DESCRIPTION =
+    "Open this conversation on another conversation's work as it stands now, with none of that conversation's messages: for a review or a test that should judge the work, not the reasoning behind it. Its edits go back into that work. First turn only, and only on a private copy.";
+
+// The turn's own rules for `freshOf`: a new private copy of its own, never beside a fork's copy of a chat, never on itself.
+export const freshOfIssues = (
+    turn: { readonly freshOf?: FreshOf | undefined; readonly conversationId?: string | undefined; readonly isolated?: boolean | undefined; readonly forkOf?: unknown },
+    ctx: z.RefinementCtx,
+): void => {
+    if (turn.freshOf === undefined) {
+        return;
+    }
+    if (turn.conversationId === undefined || turn.isolated !== true) {
+        ctx.addIssue({ code: "custom", message: "freshOf requires an isolated conversationId" });
+    }
+    if (turn.forkOf !== undefined) {
+        ctx.addIssue({ code: "custom", message: "freshOf and forkOf are two different starts: a fork carries the conversation, a fresh session carries none of it" });
+    }
+    if (turn.freshOf.conversationId === turn.conversationId) {
+        ctx.addIssue({ code: "custom", message: "a conversation cannot start fresh on its own work" });
+    }
+};

package/src/schemas/data-protection.ts

@@ -4,7 +4,7 @@
 // behaviour except for restore points: that copy grows without bound on disk. Thirty days still covers recovering a
 // deleted file; zero remains available for people who want every snapshot. The public-office preset sets the rest.
 import { z } from "zod";
-import type { AdmissionRule } from "./agent.js";
+import type { AdmissionRule } from "./command-admission.js";
 
 export const AgentRetentionDaysSchema = z
     .number()

package/src/schemas/devices.ts

@@ -117,13 +117,13 @@ export type DeviceSandbox = z.infer<typeof DeviceSandboxSchema>;
 // One operation on one sandbox, streamed as lines ending in a `result` or `error` frame. `prepare` builds the pending
 // update without touching the container. `set-shape` sets its resources and privileges, now or for the next restart;
 // `forget-shape` drops a shape saved for the next restart. `start`/`restart` apply a saved shape (all through `ic`).
-// `reshape` is the older spelling of `set-shape`, kept one release for pages served by older sandboxes.
-// `runner-up`/`runner-remove` act on a runner (this sandbox's own container), not a person's sandbox; gated by the
-// `sandboxes` switch, not removal, since a runner holds no separate workspace to lose.
+// `reshape` is `set-shape`'s older spelling, kept one release. `runner-up`/`runner-remove` act on a runner (this
+// sandbox's own container); gated by the `sandboxes` switch, not removal, as a runner holds no workspace to lose.
 export const DeviceSandboxOpSchema = z.enum([
     "start",
     "stop",
     "restart",
+    "sleep",
     "prepare",
     // `prepare` under the unattended rules (`ic sandbox prepare --auto`): nobody pressed anything, so low disk is "not
     // now" and a pinned sandbox or the version it went back from is left alone. What the update card sends by itself
@@ -203,7 +203,7 @@ export const icShapeArgs = (slug: string, fields: SandboxShapeFields, when: Sand
 ];
 export const icForgetShapeArgs = (slug: string): string[] => ["sandbox", "shape", slug, "--forget"];
 // Power goes through ic too, so a Start or Restart from any door applies the shape saved for the next restart.
-export const icPowerArgs = (op: "start" | "stop" | "restart", slug: string): string[] => ["sandbox", op, slug];
+export const icPowerArgs = (op: "start" | "stop" | "restart" | "sleep", slug: string): string[] => ["sandbox", op, slug];
 // Adds the device id to the flow input; the daemon looks up machines by id. `resumeTurns` is the owner saying, as they
 // restart the sandbox relaying this, that the turns it cuts should run again once it is back; the daemon keeps it for
 // its next boot and never forwards it to the machine. A sandbox older than it ignores it, and the cut turns wait.

package/src/schemas/hosts.ts

@@ -113,6 +113,8 @@ export type DeviceFacts = z.infer<typeof DeviceFactsSchema>;
 // - `keyring`: the keyring* procedures, intentic-keyring on this computer reached through the machine (keyring.ts);
 //   advertised only while a keyring is installed, so a sandbox never offers a computer without one as a place to keep or
 //   type a secret.
+// - `sleep`: the `sleep` op, a sandbox put to sleep now (`ic sandbox sleep <slug>`): stopped, and started again by
+//   itself when somebody opens it; advertised only when the agent's `ic` has `sandbox sleep`.
 export const DeviceFeatureSchema = z.enum([
     "reshape-later",
     "set-shape",
@@ -122,6 +124,7 @@ export const DeviceFeatureSchema = z.enum([
     "project-delivery",
     "programs",
     "keyring",
+    "sleep",
 ]);
 export type DeviceFeature = z.infer<typeof DeviceFeatureSchema>;
 export const DEVICE_FEATURE_RESHAPE_LATER: DeviceFeature = "reshape-later";
@@ -132,6 +135,7 @@ export const DEVICE_FEATURE_BACKGROUND_PREPARE: DeviceFeature = "background-prep
 export const DEVICE_FEATURE_PROJECT_DELIVERY: DeviceFeature = "project-delivery";
 export const DEVICE_FEATURE_PROGRAMS: DeviceFeature = "programs";
 export const DEVICE_FEATURE_KEYRING: DeviceFeature = "keyring";
+export const DEVICE_FEATURE_SLEEP: DeviceFeature = "sleep";
 // The features an agent advertised that this build knows; an unknown one is a newer agent's and means nothing here.
 export const deviceFeatures = (facts: Pick<DeviceFacts, "features"> | undefined): DeviceFeature[] =>
     (facts?.features ?? []).flatMap((feature) => {

package/src/schemas/keyring-native.test.ts

@@ -0,0 +1,13 @@
+import { KEYRING_NAME_RE, KeyringCaptureOutcomeSchema, KeyringRefusalCodeSchema } from "./keyring.js";
+import { KeyringNativeNameSchema, KeyringNativeOutcomeSchema, KeyringNativeRefusalCodeSchema } from "./keyring-native.js";
+
+// keyring-native.ts spells three of keyring.ts's schemas again so the browser extension's bundle never reaches keyring.ts
+// (and the zod namespace it imports); these hold the two spellings equal.
+
+test("the extension's copies of keyring.ts's names, refusals and outcomes are the same", () => {
+    expect(KeyringNativeRefusalCodeSchema.options).toEqual(KeyringRefusalCodeSchema.options);
+    expect(KeyringNativeOutcomeSchema.options).toEqual(KeyringCaptureOutcomeSchema.options);
+    for (const name of ["GITHUB_COM", "_1PASSWORD", "a", "1BAD", "has-dash", ""]) {
+        expect(KeyringNativeNameSchema.safeParse(name).success).toBe(KEYRING_NAME_RE.test(name));
+    }
+});

package/src/schemas/keyring-native.ts

@@ -0,0 +1,101 @@
+// Named imports rather than the `z` namespace, and nothing from schemas/keyring.ts: this module is bundled into the
+// browser extension, where the namespace keeps zod's locales (~330 kB) that esbuild can otherwise drop
+// (_devices/webext/scripts/size-budget.mjs holds the ceiling). The three schemas it shares with keyring.ts are spelled
+// again below, and keyring-native.test.ts holds them equal.
+import { array, boolean, discriminatedUnion, enum as zEnum, literal, number, object, string, union } from "zod";
+import type * as z from "zod";
+
+// What the browser extension and `intentic-keyring native-host` say to each other over Chrome's native messaging: one
+// JSON message each way per request, length-prefixed by the browser, correlated by `id`. The native host is a process
+// the browser starts as the person's user; it seals a captured value to the vault's inbox key before it reaches the
+// keyring's pipe, and asks the keyring (which asks the person, with Windows Hello or polkit) before any value goes back
+// to the page. A site's host, never a full address, is all the extension ever names.
+//
+// `@intentic/sandbox-contract/webext` re-exports it.
+
+/** The name the extension connects to (`chrome.runtime.connectNative`), and the native host's manifest declares. */
+export const KEYRING_NATIVE_HOST = "dev.intentic.keyring";
+
+const id = string().min(1).max(64);
+const host = string().min(1).max(253);
+
+/** keyring.ts's secret name, refusal code and capture outcome, as the extension sees them. */
+export const KeyringNativeNameSchema = string().regex(/^[A-Za-z_][A-Za-z0-9_]{0,127}$/u);
+export const KeyringNativeRefusalCodeSchema = zEnum([
+    "no-keyring",
+    "locked",
+    "declined",
+    "unknown",
+    "not-shared",
+    "bad-grant",
+    "expired",
+    "replayed",
+    "guard",
+    "unavailable",
+    "busy",
+    "pending",
+]);
+export const KeyringNativeOutcomeSchema = zEnum(["saved", "updated", "unchanged", "pending", "skipped"]);
+
+export const KeyringNativeRequestSchema = discriminatedUnion("type", [
+    // What the extension needs before it shows anything: whether remembering is on for browsers, and the vault's state.
+    object({
+        type: literal("hello"),
+        id,
+        browser: string().min(1).max(100).describe("The browser's own name, `Brave`, for the title line."),
+    }).strict(),
+    // A sign-in, sign-up or password change the page just submitted.
+    object({
+        type: literal("capture"),
+        id,
+        browser: string().min(1).max(100),
+        host,
+        username: string().max(256).optional(),
+        password: string().min(1).max(4096),
+        title: string().max(200).optional().describe("The site's own name (`og:site_name`, the title), when it has one."),
+        failed: boolean().optional().describe("The form came back for the same user: the last value saved for it did not work."),
+    }).strict(),
+    // What the keyring holds for this site: names, titles and users, never values.
+    object({ type: literal("candidates"), id, host }).strict(),
+    // One entry's value for the focused field, after the person's yes at the computer.
+    object({ type: literal("fill"), id, host, name: KeyringNativeNameSchema }).strict(),
+    // Take back a capture made moments ago (the toast's Undo).
+    object({ type: literal("undo"), id, name: KeyringNativeNameSchema, at: number().int() }).strict(),
+    // Never save for this site (the toast's "Never for this site").
+    object({ type: literal("never"), id, host }).strict(),
+]);
+export type KeyringNativeRequest = z.infer<typeof KeyringNativeRequestSchema>;
+
+const refused = object({ ok: literal(false), code: KeyringNativeRefusalCodeSchema, refusal: string() });
+
+export const KeyringNativeCandidateSchema = object({ name: KeyringNativeNameSchema, title: string(), username: string().optional() });
+export type KeyringNativeCandidate = z.infer<typeof KeyringNativeCandidateSchema>;
+
+// A plain union: a refusal shares its `type` with the answer it stands in for, which a discriminated union cannot hold.
+export const KeyringNativeResponseSchema = union([
+    object({
+        type: literal("hello"),
+        id,
+        ok: literal(true),
+        setUp: boolean(),
+        locked: boolean(),
+        remember: boolean().describe("Whether the person turned on remembering for browsers."),
+        version: string(),
+    }),
+    object({
+        type: literal("capture"),
+        id,
+        ok: literal(true),
+        outcome: KeyringNativeOutcomeSchema,
+        name: KeyringNativeNameSchema.optional(),
+        title: string().optional(),
+        at: number().int(),
+    }),
+    object({ type: literal("candidates"), id, ok: literal(true), items: array(KeyringNativeCandidateSchema) }),
+    object({ type: literal("fill"), id, ok: literal(true), username: string().optional(), password: string() }),
+    object({ type: literal("undo"), id, ok: literal(true) }),
+    object({ type: literal("never"), id, ok: literal(true) }),
+    // Any request refused, under the type it was asked as.
+    refused.extend({ type: zEnum(["hello", "capture", "candidates", "fill", "undo", "never"]), id }),
+]);
+export type KeyringNativeResponse = z.infer<typeof KeyringNativeResponseSchema>;