@intentic/sandbox-contract 1.169.0 → 1.171.0

package/src/tunnel-ids.test.ts

@@ -0,0 +1,49 @@
+import { expect, test } from "vitest";
+import { hostSshIdFromToken, PORT_SLOT_COUNT, portSlotsFromToken, sandboxIdFromToken } from "./tunnel-ids.js";
+
+const TOKEN = "connect-token-one";
+const OTHER = "connect-token-two";
+
+test("the sandbox id is a stable 12-hex digest of the connect token, and absent without one", () => {
+    expect(sandboxIdFromToken(TOKEN)).toMatch(/^[0-9a-f]{12}$/);
+    expect(sandboxIdFromToken(TOKEN)).toBe(sandboxIdFromToken(TOKEN));
+    expect(sandboxIdFromToken(OTHER)).not.toBe(sandboxIdFromToken(TOKEN));
+    expect(sandboxIdFromToken("")).toBeUndefined();
+});
+
+test("a host ssh id is salted per host, so two deploy targets never collide", () => {
+    expect(hostSshIdFromToken(TOKEN, "web-1")).toMatch(/^[0-9a-f]{12}$/);
+    expect(hostSshIdFromToken(TOKEN, "web-1")).not.toBe(hostSshIdFromToken(TOKEN, "web-2"));
+});
+
+test("port slots are a fixed-size pool of DNS-safe labels, stable per token", () => {
+    const slots = portSlotsFromToken(TOKEN);
+    // Fixed size: the pool is the cap on preview DNS records a sandbox costs the shared zone.
+    expect(slots).toHaveLength(PORT_SLOT_COUNT);
+    // Every label must survive as one DNS label AND pass the platform's mint filter
+    // (/^(preview|port)-[a-z0-9][a-z0-9-]*$/, ≤50 chars), which `port-<slot>` has to satisfy.
+    for (const slot of slots) {
+        expect(slot).toMatch(/^[0-9a-f]{12}$/);
+        expect(`port-${slot}`).toMatch(/^port-[a-z0-9][a-z0-9-]*$/);
+        expect(`port-${slot}`.length).toBeLessThanOrEqual(50);
+    }
+    // Distinct, or two forwards would fight over one hostname.
+    expect(new Set(slots).size).toBe(PORT_SLOT_COUNT);
+    // Stable: the daemon and the platform derive these independently and must agree, and a restart has to
+    // land on the records already minted rather than orphaning them.
+    expect(portSlotsFromToken(TOKEN)).toEqual(slots);
+});
+
+/* The whole point of the salt. The sandbox id is public — it is the leading label of the sandbox's own URL and
+ * of every preview link its owner has shared — so anything derived from the id ALONE is derivable by whoever
+ * holds one of those links. Slots must not be: knowing a sandbox's id must not tell you where its forwarded
+ * ports live. */
+test("slots are not derivable from the sandbox id — only from the token behind it", () => {
+    expect(portSlotsFromToken(OTHER)).not.toEqual(portSlotsFromToken(TOKEN));
+    // No slot leaks the id it will be paired with in `port-<slot>-<sandboxId>`.
+    const id = sandboxIdFromToken(TOKEN);
+    expect(id).toBeDefined();
+    expect(portSlotsFromToken(TOKEN)).not.toContain(id);
+    // And none of them is the old fixed alphabet, which is what made the hostnames guessable.
+    expect(portSlotsFromToken(TOKEN).some((slot) => slot.length === 1)).toBe(false);
+});

package/src/tunnel-ids.ts

@@ -17,3 +17,27 @@ export const sandboxIdFromToken = (connectToken: string): string | undefined =>
 // 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));

package/src/workspace-state.ts

@@ -77,11 +77,24 @@ export const WORKSPACE_STATE_FILES: readonly WorkspaceStateFile[] = [
      * Both entries below are outside that by design, so an empty set is the honest record — naming a key no
      * query uses would put the drift this table exists to remove straight back into it. Each says which
      * constraint would have to move first, so the next reader doesn't re-derive it. */
+    {
+        path: ".intentic/webchat-sessions.json",
+        invalidates: [],
+        why: "Doorbell thread bookkeeping (visitor thread → sandbox conversation + provider session), written on EVERY visitor message. Nothing in the browser reads it: what a visitor's chat produces is a conversation, and the fleet board already learns about that from the agent registry's own push. Naming a key here would bill every connected browser a refetch per inbound message — the request storm this table's own note warns about — to refresh nothing it can see.",
+    },
     {
         path: ".intentic/extension-settings.json",
         invalidates: [],
         why: "Held in a module-level shallowRef store per extension (web's extensionSettingsStore) with no query observer, and deliberately so: api.settings.get must answer SYNCHRONOUSLY from an extension's first activate() line, and the store outlives every component scope. A module-level QueryObserver is the one shape that would make invalidation refetch, and this app already ruled it out — it detaches on the queryClient.clear() at logout (see useSandbox's sandbox-list mirror). So a remote member's setting edit reaches this browser on its next load, not live.",
     },
+    /* Unlike the settings file above it, the on/off switch IS observed by a query — the Extensions tab's list,
+     * which carries each row's switch position — so a flip made elsewhere (another member, the agent writing the
+     * file) shows up here live. It does not re-run the host: activating or retiring an extension is the loader's
+     * reconcile, which the tab's own toggle triggers, so a remote flip takes effect on this browser's next load. */
+    {
+        path: ".intentic/extension-enablement.json",
+        invalidates: ["extensions"],
+    },
     {
         path: ".intentic/members.json",
         invalidates: [],