@intentic/sandbox-contract 1.247.0 → 1.249.0

package/src/tunnel-ids.ts

@@ -1,57 +0,0 @@
-import { createHash } from "node:crypto";
-
-// The one sha256-hex digest every stable content/token identity derives from: the tunnel ids below, the
-// platform's token lookup digest, the sandbox's bridge-token hashes and environment-overlay hash, hashline
-// anchors. node:crypto → this subpath is node-only.
-export const sha256Hex = (value: string): string => createHash("sha256").update(value).digest("hex");
-
-// The sandbox's stable 12-hex id, digested from the connect token. Used by:
-//   • the hostname builders beside it (hostnames.ts) — every public name embeds this id
-//   • the platform's reachability grant mint and tunnelId lookup (reachability.ts, ingress-contract.ts)
-//   • the desktop agent's loopback-port derivation for the direct-dial shortcut (daemon-base.ts)
-// All of them MUST agree on the digest, so it lives in the contract they share.
-export const sandboxIdFromToken = (connectToken: string): string | undefined =>
-    connectToken === "" ? undefined : sha256Hex(connectToken).slice(0, 12);
-
-// A per-host SSH tunnel's stable 12-hex id, salted with the host name so each enrolled deploy target gets its
-// own ssh-<id>.<zone> (no collision across hosts). Shared by the CLI (createHostSshTunnel) and the platform API
-// (provisionHostSshTunnel), which MUST derive the identical id.
-export const hostSshIdFromToken = (connectToken: string, hostName: string): string => sha256Hex(`${connectToken}:${hostName}`).slice(0, 12);
-
-/* How many port-forward slots a sandbox has. Eight is enough for a monorepo's worth of concurrent dev servers,
- * and it is the hard cap on preview DNS records a sandbox can ever cost the shared intentic zone. */
-export const PORT_SLOT_COUNT = 8;
-
-/* THE PORT-FORWARD SLOT LABELS, the `port-<slot>` half of `port-<slot>-<sandboxId>.<zone>`.
- *
- * These were the letters a…h, and that was the hole: a forwarded port's hostname was then a pure function of the
- * sandbox id, and the sandbox id is not a secret, it is the leading label of the URL the owner uses daily and
- * of every preview link they have ever shared. So anyone who had seen ONE preview link could poll eight fixed
- * names forever and catch whatever the owner forwarded, at any point in the future. The Ports view says a
- * forwarded port is public, and it is; what it could not say was that "public" meant eight guessable URLs.
- *
- * Salting with the connect token fixes that without costing anything the letters bought. Still exactly eight
- * records (the reason slots exist at all, the intentic-provided zone mints per label, and dev servers churn
- * ephemeral ports far faster than DNS should), still stable across restarts so a slot's record stays warm, and
- * still derivable with no coordination by every party that already holds the token: the daemon that forwards,
- * and the platform that mints the DNS. A party without the token has no business predicting these names.
- *
- * The browser is deliberately NOT one of those parties, it never derives a port hostname, it reads `previewUrl`
- * off the daemon's response, which is why this can live here, in the node-only half of the contract, next to
- * the digest it shares with sandboxIdFromToken. */
-export const portSlotsFromToken = (connectToken: string): readonly string[] =>
-    Array.from({ length: PORT_SLOT_COUNT }, (_, index) => sha256Hex(`${connectToken}:port:${index}`).slice(0, 12));
-
-/* THE OUTBOX SLOT, the `public-<slot>` half of `public-<slot>-<sandboxId>.<zone>`, where the daemon serves the
- * workspace's `public/` directory (PUBLIC_DIR in @intentic/workspace-ignore).
- *
- * Salted for the reason above, and it matters more here than it does for ports: a forwarded port is a live
- * server the owner started minutes ago, whereas a published file sits there. One record per sandbox, stable
- * across restarts so a link stays good for as long as the file does, and derivable only by parties holding the
- * token, the daemon that serves and the platform that mints. Not the browser: it reads the URL off the /public
- * response, exactly as it reads previewUrl off /ports.
- *
- * The unguessable hostname is also what carries the security story, because the files under it have no auth in
- * front of them: with no directory listing (public-files.ts refuses one) an outsider must guess a 12-hex label
- * AND a filename to reach anything at all. */
-export const publicSlotFromToken = (connectToken: string): string => sha256Hex(`${connectToken}:public`).slice(0, 12);

package/src/versions.ts

@@ -1,48 +0,0 @@
-/* COMPARING THE VERSIONS THIS SYSTEM STAMPS ON WHAT IT SHIPS, the daemon, the sandbox image, and the two agents
- * that run on a user's own device. One release stamps all of them to the SAME version, so "is this one behind
- * that one" is one question with one answer, and it lives here because both ends ask it: the daemon compares its
- * own build against the latest published release, and the browser compares a device's agent against the same.
- *
- * Shared rather than copied because the two copies would not disagree until the day it mattered: 1.9.0 against
- * 1.10.0 is where a hand-rolled comparator goes wrong, and it goes wrong by reporting "up to date". */
-
-// Release versions are plain dotted numerics (semantic-release picks them), so there is no semver dependency to
-// take on. A MISSING segment counts as 0, which is what makes "1.2" and "1.2.0" the same version rather than
-// adjacent ones.
-export const isNewer = (a: string, b: string): boolean => {
-    const left = a.split(".").map(Number);
-    const right = b.split(".").map(Number);
-    for (let i = 0; i < Math.max(left.length, right.length); i++) {
-        const l = left[i] ?? 0;
-        const r = right[i] ?? 0;
-        if (l !== r) {
-            return l > r;
-        }
-    }
-    return false;
-};
-
-/* The sentinel every build that is NOT a release carries: the repo keeps 0.0.0 in package.json and only
- * semantic-release stamps a real one, so a working-tree daemon and a locally-compiled agent both answer this.
- *
- * It has to be excluded from the comparison rather than merely lose it. Every published release outranks 0.0.0,
- * so a developer running the agent they just built would be told, permanently, to replace it with something
- * older than what they are running. The daemon already draws exactly this line for itself (isDevBuild). */
-export const DEV_VERSION = `0.0.0`;
-
-/* WHETHER TO TELL SOMEBODY THEIR BUILD IS OLD. Deliberately false in every uncertain case, and each one is a
- * different kind of not-knowing:
- *
- *   • no installed version, the thing does not report one, so there is nothing to be behind.
- *   • no latest version, this sandbox has not reached the registry (or is a dev build and never will).
- *   • installed is the dev sentinel, see above; a nag that cannot be satisfied is worse than silence.
- *
- * A version that is not dotted-numeric is compared by its numeric prefix, which is both useful and safe in the
- * only direction that matters: a segment that will not parse compares as neither greater nor less, so it stops
- * the comparison at "not newer". A malformed INSTALLED version can therefore only ever withhold a nag, never
- * invent one, and `latest` comes from the registry, so it is well-formed by construction.
- *
- * The asymmetry is the point. Saying "you are out of date" wrongly sends someone to reinstall a working agent;
- * saying nothing wrongly leaves them where they already were. */
-export const isBehind = (installed: string | undefined, latest: string | undefined): boolean =>
-    installed !== undefined && latest !== undefined && installed !== DEV_VERSION && isNewer(latest, installed);

package/src/webext-links.ts

@@ -1,90 +0,0 @@
-/* THE ZOD-FREE HALF OF THE BROWSER CONNECTOR'S WIRE: three URL builders, one code format, two message names.
- *
- * Split out of webext-protocol.ts for exactly one reason, and it is a real one rather than tidiness. A browser
- * extension's CONTENT SCRIPT — the few lines that run on the sandbox's own page to hand a pairing code over —
- * needs two of these constants and nothing else. Importing them through the contract's barrel pulls in every
- * schema this repo has and the whole of zod with them: measured at 1.1 MB of JavaScript injected into a page,
- * for two strings. Nothing here imports anything, so that file is now a few hundred bytes.
- *
- * The rule for what may live here: no imports, ever. A zod schema in this file would undo the split silently.
- */
-
-// The URL the extension dials, given the sandbox's public URL. Carries no credential — the token rides the
-// hello frame (webext-protocol.ts). One place builds it, so the extension and the daemon route cannot disagree
-// about where the door is.
-export const webextConnectUrl = (sandboxUrl: string): string => `${sandboxUrl.replace(/^http/, "ws").replace(/\/$/, "")}/system/webext/connect`;
-
-/* Where the extension POSTS a site's session when the owner asks for one to be handed to the sandbox
- * ("Connect this site"), authenticated by the same enrollment token as a bearer.
- *
- * A SEPARATE DOOR FROM THE SOCKET, deliberately, and this is the load-bearing decision of that feature: the
- * socket's answers are MCP tool results, which means they land in the agent's context. Cookies must never do
- * that. So the payload goes browser → daemon directly, the agent's tool call gets back a sentence and a count,
- * and the one thing that would be catastrophic to leak is the one thing the model never sees. */
-export const webextSessionUrl = (sandboxUrl: string): string => `${sandboxUrl.replace(/\/$/, "")}/system/webext/session`;
-
-/* The same door in the other direction: where the extension asks for a sandbox account's session to be LENT to
- * this browser, so the owner can finish a step no remote browser can do — a passkey, a hardware second factor,
- * an employer's SSO that checks the device.
- *
- * A separate path rather than a verb on the one above, because the two are different acts with different
- * refusals ("no such account" versus "that account is not signed in there") and a single endpoint doing both
- * would have to be read twice to know which. Same bearer, and the same rule about the socket: the cookies come
- * back on THIS request, never as an MCP result. */
-export const webextLendUrl = (sandboxUrl: string): string => `${sandboxUrl.replace(/\/$/, "")}/system/webext/lend`;
-
-/* ---- the pairing code: the one string that travels from the sandbox's card into the extension ----
- *
- * A connected device is paired by a shell one-liner, which can carry two values in two environment variables
- * because a terminal is a place where long strings are normal. A browser extension's popup is not: what a
- * person will actually do there is paste ONE thing, once, and anything that asks them to copy a URL into one
- * box and a token into another is a flow that fails on the second box.
- *
- * So both halves ride in one code. It is not encryption and does not pretend to be — base64url of two fields,
- * so that the thing on the clipboard is opaque enough not to be edited by hand, short enough to paste, and
- * carries its own sandbox address, which is the field a person could not possibly be expected to type. The
- * secret in it is the pairing token, which is single-use and expires in ten minutes (the daemon's peer store).
- *
- * The prefix is a version marker, and it is here so that a code from an older sandbox meets a clear "this code
- * is from a different version" in the extension rather than a JSON parse error. */
-const PAIRING_PREFIX = "ixb1_";
-
-const base64url = (value: string): string => btoa(value).replaceAll("+", "-").replaceAll("/", "_").replaceAll("=", "");
-
-export const webextPairingCode = (pairing: { readonly url: string; readonly token: string }): string =>
-    `${PAIRING_PREFIX}${base64url(JSON.stringify({ url: pairing.url, token: pairing.token }))}`;
-
-// The extension's side. Undefined for anything that is not one of ours, so a person who pasted the wrong thing
-// is told that rather than watching a connection attempt to nowhere.
-export const parseWebextPairingCode = (code: string): { readonly url: string; readonly token: string } | undefined => {
-    const trimmed = code.trim();
-    if (!trimmed.startsWith(PAIRING_PREFIX)) {
-        return undefined;
-    }
-    try {
-        const decoded = JSON.parse(atob(trimmed.slice(PAIRING_PREFIX.length).replaceAll("-", "+").replaceAll("_", "/"))) as {
-            url?: unknown;
-            token?: unknown;
-        };
-        // An http(s) URL and a non-empty token, or nothing: the extension is about to open a socket to whatever
-        // this says, so "looks like a URL" is checked here rather than by the WebSocket constructor throwing.
-        if (typeof decoded.url !== "string" || typeof decoded.token !== "string" || decoded.token === "" || !/^https?:\/\//.test(decoded.url)) {
-            return undefined;
-        }
-        return { url: decoded.url, token: decoded.token };
-    } catch {
-        return undefined;
-    }
-};
-
-/* How the sandbox's own page hands that code over without anybody copying anything: it posts this message on
- * its own window, and the extension's content script (which is only ever loaded on the sandbox's own origins)
- * picks it up and answers.
- *
- * A window message rather than `chrome.runtime.sendMessage` from the page, which would be the obvious route,
- * because that one needs the extension's STORE ID baked into the web app — a value that does not exist until
- * the listing is approved, differs for an unlisted build, and would make a locally-loaded extension
- * un-pairable. A window message needs neither side to know the other's identity: the content script is proof
- * enough that the extension is installed, and the page's origin is proof enough for the extension. */
-export const WEBEXT_PAIR_MESSAGE = "intentic:webext:pair";
-export const WEBEXT_PAIRED_MESSAGE = "intentic:webext:paired";

package/src/webext-protocol.ts

@@ -1,27 +0,0 @@
-import { z } from "zod";
-
-/* The handshake on /system/webext/connect, the ONE message on that socket that is not oRPC.
- *
- * Same two-phase shape as a connected device's (host-protocol.ts) and for the same reason: the daemon has
- * nothing to call until it knows whose socket this is, so the proof cannot itself be an oRPC call. The browser
- * extension's first frame carries its enrollment token, the daemon resolves WHICH capability it belongs to, and
- * from that message on every byte is `webextContract` with the EXTENSION serving.
- *
- * WHY A SEPARATE PROTOCOL FROM host's, when the frame is the same two fields: because the thing on the other
- * end is not a device. It has no shell, no filesystem and no screen; what it has is tabs, origins the person
- * granted one at a time, and a human watching every click. Sharing the host's schema would have meant a card of
- * switches that mean nothing (`roots`, `sandboxRemove`) and an agent told about a home directory it cannot
- * reach. The two connectors are siblings, not one connector with a flag. */
-
-export const WebExtHelloSchema = z.object({
-    type: z.literal("hello"),
-    /* The extension's enrollment token, in the FIRST FRAME, never in the URL: a WebSocket has no headers, and
-     * `?token=` would write a durable key into every proxy log between a browser and the sandbox. Until this
-     * arrives the socket is anonymous and short-lived. */
-    token: z.string(),
-    // The extension build the browser is running. Surfaced per connection so an old, un-updated extension is
-    // visible rather than mysteriously missing a tool. What the BROWSER is (`describe`) is pulled over the
-    // typed link a moment later, so there is one definition of those facts rather than two.
-    version: z.string(),
-});
-export type WebExtHello = z.infer<typeof WebExtHelloSchema>;