@intentic/sandbox-contract 1.248.0 → 1.250.0

package/src/schemas/vpn.ts

@@ -1,28 +1,16 @@
 // vpn: live tunnel state + connect/disconnect
 import { z } from "zod";
-// A VPN the agent's traffic rides. One capability = one tunnel, discriminated by `provider` so a new protocol
-// is a new arm (plus a driver in the daemon's vpn/), never a reinterpretation of an existing field:
-//   wireguard, a pasted .conf, brought up with wg-quick.
-//   fortinet , a FortiGate SSL-VPN (what FortiClient's <sslvpn> connections speak), dialled with openconnect
-//               --protocol=fortinet. openconnect is the client rather than openfortivpn because it routes over
-//               tun instead of pppd: it needs exactly the tun + NET_ADMIN grant this kind already carries, and
-//               no /dev/ppp device (which the runtime allowlist does not, and should not, include).
-//   ipsec    , an IKEv1/IKEv2 tunnel with a pre-shared key and optional XAuth (FortiClient's <ipsecvpn>
-//               connections), run by strongSwan. `aggressive` mirrors FortiClient's dial-up default.
-// Connecting is NOT a config field: connect/disconnect are live operations (see vpn.contract.ts) that both the
-// user and the agent drive, so a stored tunnel's up/down state is read from the OS, never from the manifest.
-// `autoConnect` is the only persisted intent, whether the daemon dials this tunnel again on boot.
+// One capability = one tunnel, discriminated by provider; a new protocol is a new arm, never a reinterpretation of an
+// existing field.
+// wireguard: a pasted .conf, brought up with wg-quick.
+// fortinet: FortiGate SSL-VPN, dialled via openconnect --protocol=fortinet (needs tun + NET_ADMIN, not /dev/ppp).
+// ipsec: IKEv1/IKEv2 with a pre-shared key and optional XAuth, run by strongSwan.
+// Connecting is a live operation read from the OS, never stored; autoConnect is the only persisted intent.
 export const VpnProviderSchema = z.enum(["wireguard", "fortinet", "ipsec"]);
 export type VpnProvider = z.infer<typeof VpnProviderSchema>;
 const autoConnect = z.enum(["on", "off"]).default("on");
-// FortiClient wraps every stored credential in its own "EncX <hex>" (older builds: "Enc <hex>") encryption,
-// keyed to the machine that exported the config, it is NOT recoverable from the file. Pasting one is an easy
-// mistake to make, because in the XML it sits exactly where the credential belongs, and the failure it causes
-// is unreadable: phase 1 negotiates fine and IKE then reports "calculated HASH does not match HASH payload",
-// which says nothing about where the bad value came from. Rejecting it here turns that into a sentence at the
-// point of entry. (The FortiClient importer already drops these, this catches a hand-paste.)
-// Exported so the add form can flag it inline on blur instead of only on a rejected round-trip, one
-// definition of what "this is ciphertext, not a credential" means, shared by the browser and the daemon.
+// FortiClient wraps stored credentials in "EncX <hex>" (or older "Enc <hex>") encryption keyed to the exporting
+// machine; not recoverable from the file. Rejected here since pasting one fails unreadably at IKE instead.
 export const isForticlientCiphertext = (value: string): boolean => /^Enc[X]?\s+[0-9A-Fa-f]{8,}$/.test(value.trim());
 const notForticlientCiphertext = <T extends z.ZodType<string>>(field: T, label: string): T =>
     field.refine((value) => !isForticlientCiphertext(value), {
@@ -30,21 +18,20 @@ const notForticlientCiphertext = <T extends z.ZodType<string>>(field: T, label:
     }) as unknown as T;
 export const WireguardVpnConfigSchema = z.object({
     provider: z.literal("wireguard"),
-    // The pasted .conf ([Interface] + [Peer]), it holds the private key, so it's this arm's secret field.
+    // The pasted .conf ([Interface] + [Peer]); holds the private key, so it's this arm's secret field.
     config: z.string().min(1),
     autoConnect,
 });
 export const FortinetVpnConfigSchema = z.object({
     provider: z.literal("fortinet"),
-    // Gateway host only; the port is its own field so a pasted "host:port" can be split on import.
+    // Gateway host only; port is separate so a pasted "host:port" can be split on import.
     server: z.string().min(1),
     port: z.coerce.number().int().min(1).max(65535).default(443),
     username: z.string().min(1),
     password: notForticlientCiphertext(z.string().min(1), "password"),
-    // A FortiGate on a self-signed/private-CA certificate: openconnect pins this digest
-    // ("sha256:…", copied from its own refusal message) instead of trusting a CA. Absent ⇒ normal CA validation.
+    // Cert pin ("sha256:...") for a self-signed gateway; absent means normal CA validation.
     trustedCert: z.string().min(1).optional(),
-    // Some gateways scope a login to a realm/group (openconnect --usergroup, FortiClient's tunnel realm).
+    // Login realm/group some gateways require (openconnect --usergroup).
     realm: z.string().min(1).optional(),
     autoConnect,
 });
@@ -52,39 +39,20 @@ export const IpsecVpnConfigSchema = z.object({
     provider: z.literal("ipsec"),
     server: z.string().min(1),
     presharedKey: notForticlientCiphertext(z.string().min(1), "pre-shared key"),
-    // The local IKE identity (FortiClient's <localid>), dial-up FortiGates key their phase-1 selection off it.
+    // Local IKE identity; dial-up FortiGates key their phase-1 selection off it.
     localId: z.string().min(1).optional(),
     remoteId: z.string().min(1).optional(),
-    // XAuth (FortiClient's <xauth>), absent for PSK-only tunnels.
+    // XAuth credentials; absent for PSK-only tunnels.
     username: z.string().min(1).optional(),
     password: notForticlientCiphertext(z.string().min(1), "XAuth password").optional(),
     ikeVersion: z.enum(["1", "2"]).default("1"),
-    // Perfect Forward Secrecy for phase 2. Must match the gateway EXACTLY: it decides whether a KE payload is
-    // sent in quick mode, and a mismatch fails with NO_PROPOSAL_CHOSEN only after phase 1 and XAuth have
-    // succeeded, which reads like anything but a phase 2 problem. FortiClient stores it as <pfs> under
-    // <ipsec_settings> and defaults it on, so that is the default here too.
+    // Must match the gateway exactly, or it fails with NO_PROPOSAL_CHOSEN after phase 1 and XAuth succeed.
     pfs: z.enum(["on", "off"]).default("on"),
-    // The Diffie-Hellman group, as FortiClient numbers them. ONE field for both phases on purpose: in IKEv1
-    // strongSwan sends a single KE payload in quick mode and the phase-2 group ends up following phase 1, so
-    // offering a phase-1 list that starts with a different group than the gateway wants for phase 2 fails with
-    // NO_PROPOSAL_CHOSEN no matter what the esp= line says. 14 (modp2048) is FortiClient's phase-2 default;
-    // it is <dhgroup> under <ipsec_settings> in an export.
+    // One field for both phases: IKEv1 reuses the phase-1 group in quick mode, or it fails NO_PROPOSAL_CHOSEN.
     dhGroup: z.enum(["2", "5", "14", "15", "16", "19", "20"]).default("14"),
-    // IKEv1 aggressive mode: insecure by construction, and exactly what FortiGate dial-up with a group PSK
-    // requires, hence opt-in per connection rather than a global strongSwan setting.
+    // IKEv1 aggressive mode: insecure by construction, required by FortiGate dial-up with a group PSK.
     aggressive: z.enum(["on", "off"]).default("on"),
-    // WHICH networks ride the tunnel, strongSwan's rightsubnet, the traffic selector this client offers in
-    // quick mode. The single most consequential setting on an ipsec tunnel, and the one with no visible symptom
-    // until it is wrong: 0.0.0.0/0 offers the gateway EVERYTHING the sandbox sends, including the sandbox's own
-    // outbound connection to the model endpoint. A gateway that routes only its own networks accepts that
-    // selector, assigns a virtual IP, and then black-holes the rest, so the agent goes silent mid-turn, which
-    // reads as the agent breaking rather than as a VPN setting. Narrowing this to the networks actually behind
-    // the gateway (10.0.0.0/8,192.168.0.0/16) fixes it with nothing lost: the gateway is asked for less, not for
-    // something different, and it needs no change of its own to accept that.
-    // Comma-separated because strongSwan takes a list; under IKEv1 each entry is its own CHILD_SA, which not
-    // every gateway will negotiate, a list that dials as one entry is a gateway limit, not a config error.
-    // The DEFAULT STAYS 0.0.0.0/0: narrowing it for everyone would cut existing tunnels off from networks they
-    // reach today, and a full tunnel is right whenever the gateway does route the internet.
+    // strongSwan's rightsubnet, comma-separated CIDRs; default stays 0.0.0.0/0 so existing tunnels aren't narrowed.
     routedNetworks: z
         .string()
         .default("0.0.0.0/0")
@@ -106,9 +74,8 @@ export type WireguardVpnConfig = z.infer<typeof WireguardVpnConfigSchema>;
 export type FortinetVpnConfig = z.infer<typeof FortinetVpnConfigSchema>;
 export type IpsecVpnConfig = z.infer<typeof IpsecVpnConfigSchema>;
 export type VpnConfig = z.infer<typeof VpnConfigSchema>;
-// The manifest says which VPNs EXIST; this says which are UP right now. Every field is read back from the OS
-// (wg show / ip / openconnect's pidfile / swanctl), never remembered by the daemon, so a tunnel the agent
-// dropped from a shell and one the UI dropped read identically, and a daemon restart loses nothing.
+// Manifest says which VPNs exist; this says which are up. Every field reads live from the OS, never remembered, so a
+// restart loses nothing.
 
 export const VpnStateSchema = z.enum([
     // The tunnel is up and carrying traffic.
@@ -129,8 +96,7 @@ export const VpnLinkSchema = z.object({
     state: VpnStateSchema.describe(
         "Whether it is up, dialling, resting, failed, or not installable yet because its client needs a rebuild to arrive.",
     ),
-    // The gateway this tunnel dials, host:port for fortinet, the [Peer] endpoint for wireguard, the IKE peer
-    // for ipsec. Display only; never a secret.
+    // The gateway dialled: host:port, a wireguard peer, or an ipsec peer. Display only, never a secret.
     gateway: z.string().optional().describe("What it dials. For display only, and never a credential."),
     // The tun/wg interface carrying the tunnel, once it exists.
     interface: z.string().optional().describe("The network interface carrying it, once one exists."),
@@ -159,8 +125,7 @@ export const VpnListSchema = z.object({
         .array(VpnLinkSchema)
         .describe("Every configured tunnel with its live state, read back from the operating system each time rather than remembered."),
 });
-// POST /vpn/{id}/connect body. `otp` is a one-time 2FA code, supplied per dial and NEVER stored, a FortiGate
-// with token auth rejects the dial without it, and the daemon surfaces that as a retry-with-a-code error.
+// otp is a one-time 2FA code, supplied per dial and never stored; a token-auth gateway rejects the dial without it.
 export const VpnConnectInputSchema = z.object({
     id: z.string().describe("Which tunnel to dial."),
     otp: z
@@ -170,10 +135,8 @@ export const VpnConnectInputSchema = z.object({
         .describe("A one-time code, where the gateway wants one. Supplied per dial and never stored; without it such a gateway refuses and says so."),
 });
 export const VpnIdParamSchema = z.object({ id: z.string().describe("Which tunnel.") });
-// POST /vpn/import-forticlient: parse an exported FortiClient configuration (the XML FortiClient writes from
-// File → Settings → Backup) into addable connections. Credentials in that file are wrapped in FortiClient's
-// proprietary "EncX …" encryption, which is NOT reversible here, so a parsed connection carries the endpoint
-// and, when it was stored in the clear, the username; the password is always typed by the user afterwards.
+// Parses an exported FortiClient XML into addable connections. EncX-wrapped credentials are not reversible: only the
+// endpoint and any cleartext username come through; the password is always typed later.
 export const ForticlientImportInputSchema = z.object({
     xml: z.string().min(1).describe("The exported configuration file, whole. Nothing is stored: it is read and thrown away."),
 });
@@ -191,10 +154,10 @@ export const ForticlientConnectionSchema = z.object({
         .optional()
         .describe("The username, but only when the file stored it in the clear. An encrypted one is dropped rather than guessed at."),
     description: z.string().optional().describe("Whatever the file said about it."),
-    // ipsec-only, and only when the file stored them in the clear.
+    // ipsec-only; present only when the file stored it in the clear.
     localId: z.string().optional().describe("An identity some tunnel types need, when the file stored it readably."),
     aggressive: z.boolean().optional().describe("Which negotiation mode it used."),
-    // Phase-2 settings, read from <ipsec_settings>, the pair that decides whether quick mode can succeed.
+    // Phase-2 settings from <ipsec_settings>; together they decide whether quick mode can succeed.
     pfs: z.boolean().optional().describe("Whether it asked for forward secrecy."),
     dhGroup: z
         .string()
@@ -202,7 +165,7 @@ export const ForticlientConnectionSchema = z.object({
         .describe(
             "Which key-exchange group it used. Together with the setting above, this is what decides whether the connection can complete at all.",
         ),
-    // What the user still has to supply for this connection to dial (always at least the password).
+    // What the user must still type in before it can dial; always at least the password.
     needs: z
         .array(z.string())
         .describe(

package/src/schemas/webext.ts

@@ -1,64 +1,46 @@
 // webext: the user's own browser (the `webext` capability's live half)
 import { z } from "zod";
-/* ONE SITE THE PERSON ALLOWED, as the browser itself understands it. `origin` is Chrome's own match pattern
- * for that grant ("https://github.com/*"), because that is the string the extension asked `chrome.permissions`
- * for and the string the browser will show in its own settings — inventing a prettier spelling here would mean
- * a card naming something the browser's permission list does not.
- *
- * `mode` is this extension's own narrowing on top of Chrome's grant: a site may be readable without being
- * driveable. Chrome has no concept for that, so it is enforced in the extension and shown here so the card can
- * say which is which. */
+// origin is Chrome's own match pattern string for the grant, the same one the extension requested and the browser shows
+// in its settings; mode is the extension's own read/act narrowing, which Chrome has no concept of.
 export const WebExtGrantSchema = z.object({
     origin: z.string(),
     mode: z.enum(["read", "act"]),
 });
 export type WebExtGrant = z.infer<typeof WebExtGrantSchema>;
-// What a connected browser reports about itself. The parallel of HostFacts, and the same job: the SKILL pack
-// teaches the agent how to drive a browser, this tells it which browser, how many tabs are open, and — the
-// part with no equivalent on a machine — exactly which sites it may touch right now.
+// What a connected browser reports about itself: mirrors HostFacts, adding exactly which sites it may touch right now.
 export const WebExtFactsSchema = z.object({
     // How a person would name it: "Chrome 141 on Windows".
     browser: z.string(),
-    // Tabs open right now. A count rather than a list: the list is a tool call away and changes every minute,
-    // and a card that renders someone's open tabs is a card nobody wants to screenshot.
+    // Count only; the list is a separate tool call and changes too often to show here.
     tabs: z.number(),
-    /* The sites the person has allowed, live from the browser's own permission store rather than from anything
-     * this daemon remembers. It is the answer to the question every reader of this card actually has, and the
-     * only honest source for it is the browser: a grant can be revoked in Chrome's UI without the sandbox
-     * being told. */
+    // Live from the browser's permission store; a grant revoked in Chrome is not reflected until re-read.
     grants: z.array(WebExtGrantSchema),
-    // The extension's own kill switch, flipped in its popup. True ⇒ every tool refuses, and says so.
+    // Kill switch from the extension's popup; true means every tool refuses and reports why.
     paused: z.boolean(),
 });
 export type WebExtFacts = z.infer<typeof WebExtFactsSchema>;
 export const WebExtSummarySchema = z.object({
-    // The capability id, the browser's name, and the prefix of its tools (mcp__<id>__click).
+    // id is the capability id and the prefix of its tools (mcp__<id>__click).
     id: z.string(),
     platform: z.string().min(1),
     online: z.boolean(),
-    // The extension build, so a browser running an old one is visible rather than mysteriously lacking a tool.
+    // Extension build version; an old build looks outdated rather than missing a tool.
     version: z.string().optional(),
-    // Epoch ms of the last time this browser held a socket. Absent ⇒ it has not connected since this daemon
-    // booted: liveness is a fact about a socket, so a restart forgets it rather than claiming stale uptime.
+    // Epoch ms of the last socket connection; absent after a restart rather than stale.
     lastSeen: z.number().optional(),
     facts: WebExtFactsSchema.optional(),
 });
 export type WebExtSummary = z.infer<typeof WebExtSummarySchema>;
 export const WebExtsListSchema = z.object({ browsers: z.array(WebExtSummarySchema) });
-/* ---- handing a site's session to the sandbox: what the extension POSTs, and what comes back ----
- *
- * THE PAYLOAD IS A CREDENTIAL, the whole of one. It travels on its own HTTPS door (webext-protocol.ts's
- * webextSessionUrl) rather than as an answer on the socket, because socket answers are MCP results and MCP
- * results land in the model's context. Nothing here is ever logged, echoed in an error, or written anywhere
- * but the target profile's cookie store. */
+// A credential: sent via the extension's own HTTPS request (webextSessionUrl), never the socket, since socket answers
+// land in the model's context as MCP results; never logged or stored outside the target profile's cookie store.
 export const WebExtCookieSchema = z.object({
     name: z.string(),
     value: z.string(),
-    // Chrome's own spelling, leading dot and all (".github.com"): it is what the browser stored, and rewriting
-    // it here is how a session arrives that the target site does not recognise.
+    // Chrome's exact stored spelling, leading dot included; rewriting it breaks recognition by the target.
     domain: z.string(),
     path: z.string(),
-    // Epoch SECONDS, Chrome's unit. Absent ⇒ a session cookie, which dies with the browser that receives it.
+    // Epoch seconds (Chrome's unit); absent means a session cookie that dies with the receiving browser.
     expires: z.number().optional(),
     httpOnly: z.boolean(),
     secure: z.boolean(),
@@ -66,43 +48,30 @@ export const WebExtCookieSchema = z.object({
 });
 export type WebExtCookie = z.infer<typeof WebExtCookieSchema>;
 export const WebExtSessionImportSchema = z.object({
-    // The `browser`-kind capability whose profile receives this. Named by the agent from the roster it can
-    // already read, so a session can only ever land in an account the owner had already created.
+    // The `browser`-kind capability whose profile receives this; must already exist in the roster.
     account: z.string().min(1),
-    // The site this came from, for the message the owner reads afterwards. Never used to place the cookies:
-    // each cookie carries its own domain.
+    // Site of origin, shown to the owner only; each cookie carries its own domain for placement.
     origin: z.string().min(1),
-    // A ceiling rather than a guess: a big site's cookie jar for one registrable domain runs to dozens, and
-    // anything past this is a caller that misunderstood the tool, not a login.
+    // Ceiling, not a real limit: past this many cookies for one domain the caller misused the tool.
     cookies: z.array(WebExtCookieSchema).min(1).max(300),
 });
 export type WebExtSessionImport = z.infer<typeof WebExtSessionImportSchema>;
 
-/* ---- and the same door in the other direction: LENDING a sandbox session to the person's own browser ----
- *
- * The case this answers is the one no amount of streaming quality can: a passkey bound to an authenticator the
- * person physically holds, a hardware second factor that has to be touched, an employer's SSO that checks the
- * device. Driving the sandbox's browser remotely is not a worse experience on those sites, it is an impossible
- * one — so the session goes to the browser the account was actually enrolled on, the person finishes the step
- * as themselves, and `connect_site` hands it back.
- *
- * Same door and same rule as the import above: the cookies travel on the extension's own HTTPS request, never
- * as a socket answer, because socket answers are MCP results and MCP results land in the model's context. */
+// Lends a sandbox session to the person's own browser for passkeys, hardware 2FA, or device-checked SSO that remote
+// driving cannot satisfy; same HTTPS-not-socket rule as the import above.
 export const WebExtSessionExportSchema = z.object({
-    // The `browser`-kind capability to lend FROM. Named by the agent out of the roster it can already read.
+    // The `browser`-kind capability to lend from; named from the roster the agent can already read.
     account: z.string().min(1),
-    // The registrable domain to lend, and the reason this cannot lend a whole profile: a profile holds every
-    // account its owner ever connected, and handing all of it over because one site got stuck is the kind of
-    // over-broad grant that is invisible until it matters.
+    // Registrable domain only; lending the whole profile would over-grant every account it holds.
     domain: z.string().min(1),
 });
 export type WebExtSessionExport = z.infer<typeof WebExtSessionExportSchema>;
 
 export const WebExtSessionExportResultSchema = z.object({
     ok: z.boolean(),
-    // What the owner reads and the agent reads back. Never carries a cookie name or a value.
+    // Read by both the owner and the agent; never contains a cookie name or value.
     message: z.string(),
-    // Only ever read by the extension, which writes it straight into this browser's own cookie store.
+    // Read only by the extension, written straight into this browser's cookie store.
     cookies: z.array(WebExtCookieSchema).optional(),
 });
 export type WebExtSessionExportResult = z.infer<typeof WebExtSessionExportResultSchema>;