@intentic/sandbox-contract 1.233.0 → 1.235.0

package/src/credential-material.test.ts

@@ -0,0 +1,120 @@
+import { describe, expect, test } from "vitest";
+import { holdsCredentialMaterial } from "./credential-material.js";
+
+/* The two directions are not symmetric and the tests are written to say so: a MISS here costs one permission
+ * card that should not have been raised, and a WRONG CLEAR un-gates a real credential read. So the "no" cases
+ * are the ones that have to be exactly right, and every "yes" case is a real file's real shape. */
+
+describe("files that hold a credential", () => {
+    test("an npmrc with a token", () => {
+        expect(holdsCredentialMaterial("//registry.npmjs.org/:_authToken=npm_wCq3nTvR8xLm2ZbKp7HdJyE4sUaF6gN0iQ1t\n")).toBe(true);
+    });
+
+    test("an aws credentials ini", () => {
+        expect(
+            holdsCredentialMaterial("[default]\naws_access_key_id = AKIAIOSFODNN7EXAMPLE\naws_secret_access_key = wJalrXUtnFEMI/K7MDENG\n"),
+        ).toBe(true);
+    });
+
+    test("a private key file, whatever generated it", () => {
+        for (const text of [
+            "-----BEGIN OPENSSH PRIVATE KEY-----\nb3BlbnNzaC1rZXktdjEAAAAA\n-----END OPENSSH PRIVATE KEY-----\n",
+            "-----BEGIN RSA PRIVATE KEY-----\nMIIEow\n",
+            "-----BEGIN PRIVATE KEY-----\nMIIEvQ\n",
+            "PuTTY-User-Key-File-3: ssh-ed25519\nEncryption: none\n",
+        ]) {
+            expect(holdsCredentialMaterial(text), text.slice(0, 30)).toBe(true);
+        }
+    });
+
+    // `.git-credentials` is nothing but these lines, and a dotenv hides the same secret inside a connection
+    // string, where no key names it.
+    test("a password carried in a URL", () => {
+        expect(holdsCredentialMaterial("https://radarsu:ghp_S8kQ2mVx@github.com\n")).toBe(true);
+        expect(holdsCredentialMaterial("DATABASE_URL=postgres://app:Rk29fPqz@db.internal:5432/app\n")).toBe(true);
+    });
+
+    test("a dotenv with one real value among the ordinary ones", () => {
+        expect(holdsCredentialMaterial("PORT=3000\nNODE_ENV=production\nSTRIPE_SECRET=sk_live_51H8xQzRvKpLmNbTy\n")).toBe(true);
+    });
+
+    test("a json credentials file", () => {
+        expect(holdsCredentialMaterial('{"accessToken":"ya29.a0AfB_bJq2Lm","expiresAt":1767000000}')).toBe(true);
+    });
+
+    // The issuers whose tokens announce themselves, found without any key naming them.
+    test("a token that carries its own prefix", () => {
+        for (const text of [
+            "ghp_16C7e42F292c6912E7710c838347Ae178B4a",
+            "xoxb-2410-1230-AbCdEfGhIjKlMnOpQrSt",
+            "AKIAIOSFODNN7EXAMPLE",
+            "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0.dozjgNryP4J3jVmNHl0w5N_XgL0n3I9PlFUP0THsR8U",
+        ]) {
+            expect(holdsCredentialMaterial(text), text.slice(0, 20)).toBe(true);
+        }
+    });
+});
+
+describe("files that do not", () => {
+    /* THE FILE THAT STARTED THIS. An npmrc is the most-named credential path in this workspace's own commands
+     * and most of them are three lines of registry config. */
+    test("an npmrc with only registry config", () => {
+        expect(holdsCredentialMaterial("registry=https://registry.npmjs.org/\nengine-strict=true\nstore-dir=/root/.pnpm-store\n")).toBe(
+            false,
+        );
+    });
+
+    test("a dotenv of ports and flags", () => {
+        expect(holdsCredentialMaterial("PORT=3000\nNODE_ENV=development\nVITE_API_URL=http://localhost:8080\nLOG_LEVEL=debug\n")).toBe(false);
+    });
+
+    /* THE TEMPLATE THAT IS STILL A TEMPLATE. A key named `TOKEN` proves nothing on its own — half the dotenvs
+     * in a monorepo are this file, waiting for someone to fill them in. */
+    test("a dotenv whose credential keys are still placeholders", () => {
+        expect(
+            holdsCredentialMaterial(
+                [
+                    "GITHUB_TOKEN=",
+                    "NPM_TOKEN=${NPM_TOKEN}",
+                    "API_KEY=<your-api-key>",
+                    'CLIENT_SECRET=""',
+                    "DB_PASSWORD=changeme",
+                    "SLACK_TOKEN=xxxxxxxx",
+                    "STRIPE_SECRET={{secret:STRIPE}}",
+                    "AUTH_TOKEN=your-token-here",
+                    "SESSION_SECRET=REDACTED",
+                ].join("\n"),
+            ),
+        ).toBe(false);
+    });
+
+    // The public half of a keypair, and the host list beside it: named in the same directory, credential
+    // material in neither.
+    test("the public files an ssh directory is full of", () => {
+        expect(holdsCredentialMaterial("ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIH1x radarsu@omen\n")).toBe(false);
+        expect(holdsCredentialMaterial("github.com ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIOMqqnkVzr\n")).toBe(false);
+        expect(holdsCredentialMaterial("Host github.com\n  User git\n  IdentityFile ~/.ssh/id_ed25519\n")).toBe(false);
+    });
+
+    test("a key whose name only looks like one", () => {
+        expect(holdsCredentialMaterial("TOKEN_EXPIRY=3600\nREFRESH_TOKEN_URL=https://auth.example.com/refresh\nMAX_TOKENS=8192\n")).toBe(
+            false,
+        );
+    });
+
+    // A dev default is a real password in the strictest reading and nothing this class exists to stop; the
+    // length floor is what draws that line.
+    test("a dev-compose default is not what the card is for", () => {
+        expect(holdsCredentialMaterial("POSTGRES_PASSWORD=dev\nREDIS_PASSWORD=x\n")).toBe(false);
+    });
+
+    test("an empty file", () => {
+        expect(holdsCredentialMaterial("")).toBe(false);
+        expect(holdsCredentialMaterial("\n\n# nothing here\n")).toBe(false);
+    });
+
+    // A URL with a port is not a URL with a password: `user:pass@` needs both halves and the `@`.
+    test("an ordinary url is not userinfo", () => {
+        expect(holdsCredentialMaterial("API=http://localhost:8080/v1\nSENTRY_DSN=https://abc123@o1.ingest.sentry.io/1\n")).toBe(false);
+    });
+});

package/src/credential-material.ts

@@ -0,0 +1,100 @@
+/* WHETHER A FILE ACTUALLY HOLDS A CREDENTIAL, the fact that `secrets.access` only guesses at from a path.
+ *
+ * The classifier next door (command-classes.ts) reads shell text, so the strongest thing it can honestly say
+ * about `sed … ~/.npmrc` is "this names a file that USUALLY holds a token". Usually is not always, and the gap
+ * is where the class earns its reputation: most `~/.npmrc` files are three lines of registry config, most
+ * `.env` files in a monorepo are ports and feature flags, `~/.ssh/known_hosts` is a list of public keys, and a
+ * file that does not exist reads nothing at all. A card raised over one of those is not a near miss, it is
+ * noise, and noise is what teaches an owner to answer the card without reading it, which is precisely how a
+ * real credential read gets waved through six weeks later.
+ *
+ * So the class is split in two. The path table says WHICH FILES ARE WORTH LOOKING AT; this says WHAT A
+ * CREDENTIAL LOOKS LIKE once one has been opened. It lives here, beside that table, because the two halves are
+ * one definition of the class and an enforcement point that has a filesystem should not have to invent the
+ * second half for itself (guard/credential-files.ts is the sandbox's fs half; a caller with no filesystem, the
+ * browser or the machine agent, simply never asks and the path stands on its name alone).
+ *
+ * PURE, over the file's own text: no fs, no path logic, nothing to configure. That keeps this package free of
+ * a runtime the editor bundle cannot have, and keeps the rule testable as a table of strings.
+ *
+ * IT ANSWERS THE EASY DIRECTION WELL AND THE HARD ONE CONSERVATIVELY. Everything below is written to say YES
+ * on anything credential-shaped, because a yes costs one card and a no costs the whole rule: the only use of
+ * this answer is to REMOVE a class the path table already added, so a false yes leaves behavior exactly as it
+ * was and a false no silently un-gates a real read.
+ */
+
+/* A KEY THAT NAMES A CREDENTIAL, AND ITS VALUE. Matched as a suffix of whatever the key is spelled as, because
+ * these files say the same thing a dozen ways and only the last word carries the meaning: `NPM_TOKEN`,
+ * `//registry.npmjs.org/:_authToken`, `"accessToken"`, `aws_secret_access_key`, `password =`.
+ *
+ * The three value arms are the three ways a value is quoted across the formats this ever sees: JSON's double
+ * quotes, a shell-ish dotenv's single quotes, and an ini file's bare rest-of-line.
+ *
+ * THE SEPARATOR MAY NOT CROSS A LINE, which is the difference between reading a file and reading a soup: with
+ * `\s*` around it, an empty `GITHUB_TOKEN=` borrows the NEXT line as its value, and a dotenv of nine blank
+ * placeholders reads as eight credentials. Every format here puts a value on its key's own line. */
+const CREDENTIAL_ASSIGNMENT =
+    /(?:auth[_-]?token|access[_-]?token|refresh[_-]?token|api[_-]?key|access[_-]?key|secret[_-]?key|client[_-]?secret|private[_-]?key|passwo?rd|passphrase|credentials?|secret|token|bearer)["']?[ \t]*[:=][ \t]*(?:"([^"\n]*)"|'([^'\n]*)'|([^\s"',;}\n]*))/gi;
+
+/* A VALUE THAT IS NOT A CREDENTIAL EVEN THOUGH ITS KEY SAYS IT IS: the empty one, the one still holding the
+ * template's own words, and the one deferring to an environment variable or a secret reference. Every dotenv
+ * that ships in a repo is made of these, and firing on `GITHUB_TOKEN=${GITHUB_TOKEN}` would put a card in front
+ * of reading a file whose entire content is the absence of a secret. */
+const PLACEHOLDER =
+    /^(?:\$\{?[\w:.-]+\}?|\{\{[^}]*\}\}|<[^>]*>|%\w+%|x{3,}|\*{3,}|\.{3,}|…|(?:your|my|our|the)[-_\s].*|change[-_]?me|replace[-_]?(?:me|this|with)|todo|tbd|fixme|none|null|nil|undefined|true|false|example|placeholder|redacted|dummy|sample|test|fake|secret|password|token|value|here)$/i;
+
+/* Shorter than any credential a service actually issues. It clears the dev-compose defaults an agent reads all
+ * day (`POSTGRES_PASSWORD=dev`, `password=x`), which are not what a card asking about credential material is
+ * for, and it is well under the shortest real token below (a 36-character npm one). */
+const MIN_VALUE = 6;
+
+/* A CREDENTIAL RECOGNISABLE WITHOUT ITS KEY: the issuers whose tokens carry their own prefix, the PEM and PuTTY
+ * headers that ARE the private key file, and a URL that carries a password in its userinfo (which is the whole
+ * content of `.git-credentials`, and the shape a `DATABASE_URL` hides one in).
+ *
+ * These are checked first and independently of any key, because half of these files have no `key = value` in
+ * them at all. */
+const TOKEN_SHAPES = [
+    /-----BEGIN (?:[A-Z0-9]+ )*PRIVATE KEY-----/,
+    /PuTTY-User-Key-File-\d/,
+    // scheme://user:password@host — the password is the point; a Sentry DSN (`https://key@host`) has no colon
+    // before the `@` and is deliberately not this.
+    /\b[a-z][a-z0-9+.-]*:\/\/[^\s/:@]+:[^\s/@]{3,}@/i,
+    /\bnpm_[A-Za-z0-9]{30,}/,
+    /\b(?:ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9]{30,}/,
+    /\bgithub_pat_[A-Za-z0-9_]{50,}/,
+    /\bglpat-[A-Za-z0-9_-]{16,}/,
+    /\bxox[baprs]-[A-Za-z0-9-]{10,}/,
+    /\bsk-[A-Za-z0-9_-]{20,}/,
+    /\b(?:sk|rk)_live_[A-Za-z0-9]{16,}/,
+    /\bAKIA[0-9A-Z]{16}\b/,
+    /\bASIA[0-9A-Z]{16}\b/,
+    /\bAIza[0-9A-Za-z_-]{35}\b/,
+    /\bhf_[A-Za-z0-9]{30,}/,
+    /\bdop_v1_[a-f0-9]{60,}/,
+    // A JWT: three base64url segments, the first two of which decode from `{"` and so always begin `ey`.
+    /\bey[A-Za-z0-9_-]{10,}\.ey[A-Za-z0-9_-]{10,}\./,
+];
+
+/* A VALUE DEFERRED TO SOMEWHERE ELSE, removed before anything is read, because it is not one value but two
+ * things to get wrong. `STRIPE_SECRET={{secret:STRIPE}}` holds no credential — that is the platform's own
+ * convention for a file that must not hold one — and yet it reads as a credential twice over: the outer
+ * assignment has a substantial-looking value, and the reference's own `secret:STRIPE` is a second `key: value`
+ * inside it. Cutting them out first is simpler and steadier than teaching the value patterns to survive them. */
+const DEFERRED_VALUE = /\{\{[^}\n]*\}\}|\$\{[^}\n]*\}/g;
+
+// Does this file's text hold something worth a card? Handed the WHOLE file by its caller, which is why the
+// caller (not this) is the one that decides how much of a large file is worth reading.
+export const holdsCredentialMaterial = (file: string): boolean => {
+    const text = file.replace(DEFERRED_VALUE, "");
+    if (TOKEN_SHAPES.some((pattern) => pattern.test(text))) {
+        return true;
+    }
+    for (const match of text.matchAll(CREDENTIAL_ASSIGNMENT)) {
+        const value = (match[1] ?? match[2] ?? match[3] ?? "").trim();
+        if (value.length >= MIN_VALUE && !PLACEHOLDER.test(value)) {
+            return true;
+        }
+    }
+    return false;
+};

package/src/history-state.ts

@@ -37,6 +37,18 @@ export const HISTORY_STATE_FILES: readonly StateFile[] = [
     // The fleet: every conversation card, its branch, its session ids, its standing.
     { path: "agents.json", portability: "carry" },
     { path: "turns/", portability: "carry" },
+    /* THE ARMED CONDITION WATCHES, one file per watch, put back at boot (agent/watchers.ts `restoreWatchers`).
+     *
+     * Carried for the reason loops.json is: an arrangement the agent entered into on the user's behalf and
+     * that is still outstanding travels with the conversation that is waiting on it, or a restored sandbox
+     * shows a card parked on a condition nothing will ever check. It can be carried safely because the journal
+     * holds no credential, only the NAMES of the environment its check ran with (agent/watch-journal.ts); the
+     * values are re-derived on the target from whatever capabilities it actually has, so a watch landing
+     * somewhere without them fails its check honestly and ends in a wake that says so, rather than arriving
+     * with a working copy of a token the bundle was never supposed to carry. A watch whose isolated checkout
+     * did not travel (those are `derived`) is dropped by the restore rather than re-armed against a tree that
+     * is not there. */
+    { path: "watches/", portability: "carry" },
     { path: "transcripts/", portability: "carry" },
     // What each message can be put back to, a workspace checkpoint, or an isolated conversation's own commits.
     // Carried WITH the transcripts and the scopes above, because it is the join between them: without it a

package/src/hostnames.ts

@@ -14,7 +14,7 @@ export const sandboxHostname = (id: string, zone: string): string => `${sandboxS
 // The container sshd hostname the desktop-sync (Mutagen) reaches over the sandbox tunnel: `ssh-<id>.<zone>`.
 export const sshHostname = (id: string, zone: string): string => `ssh-${id}.${zone}`;
 
-/* The LOOPBACK name: `local-<id>.<zone>`, an A record pointing at 127.0.0.1.
+/* The LOOPBACK name: `<id>.local.<zone>`, resolving to 127.0.0.1 under ONE wildcard record for the whole zone.
  *
  * A public DNS name for a private address looks odd until you ask what the alternative is. A browser on the
  * same machine as the sandbox can reach its daemon in microseconds instead of crossing to a Cloudflare edge
@@ -23,9 +23,25 @@ export const sshHostname = (id: string, zone: string): string => `ssh-${id}.${zo
  * one; this can. The daemon holds the key and gets the certificate by proving control of the zone over
  * DNS-01 (there is nothing on the public internet for a CA to connect to).
  *
+ * IT IS A LABEL DEEPER THAN THE OTHER NAMES, and that is the entire point rather than a naming preference. A
+ * DNS wildcard matches ONE label, so `*.<zone>` cannot cover `<id>.local.<zone>` and `*.local.<zone>` covers
+ * every sandbox that will ever exist: one record for the platform, not one per sandbox. The shape it replaced,
+ * `local-<id>.<zone>`, needed a record each, and a zone has a hard per-record quota (Cloudflare 81045). Every
+ * OTHER per-sandbox record went away with the move to the zrok hub, so this was the last thing consuming that
+ * quota, and when the zone filled the platform could no longer write the record OR the ACME challenge beside
+ * it: the certified shortcut stopped resolving, every browser fell back to the plain-http loopback, and that
+ * transport is HTTP/1.1 with six connections per origin (see the editor's streamBudget.ts for what that cost).
+ * A quota nothing can exhaust is the fix that keeps working.
+ *
  * It discloses nothing: the id is already the leading label of the sandbox's public hostname, and the address
  * it resolves to is every machine's own loopback. */
-export const localHostname = (id: string, zone: string): string => `local-${id}.${zone}`;
+export const localHostname = (id: string, zone: string): string => `${id}.${LOCAL_LABEL}.${zone}`;
+
+// The label the loopback names live under, so the wildcard has something to be a wildcard OF.
+export const LOCAL_LABEL = "local";
+
+// The single record that answers for all of them. Never per-sandbox, never reaped.
+export const localWildcardHostname = (zone: string): string => `*.${LOCAL_LABEL}.${zone}`;
 
 // What that record points at, and the reason it is safe to publish: every resolver on earth gets 127.0.0.1.
 export const LOCAL_ADDRESS = "127.0.0.1";

package/src/index.ts

@@ -19,6 +19,7 @@ import { grokContract } from "./contracts/grok.contract.js";
 import { historyContract } from "./contracts/history.contract.js";
 import { intenticContract } from "./contracts/intentic.contract.js";
 import { inventoryContract } from "./contracts/inventory.contract.js";
+import { issuesContract } from "./contracts/issues.contract.js";
 import { logsContract } from "./contracts/logs.contract.js";
 import { loopsContract } from "./contracts/loops.contract.js";
 import { panelsContract } from "./contracts/panels.contract.js";
@@ -66,6 +67,7 @@ export { webextContract } from "./contracts/webext.contract.js";
 export { runnerContract } from "./contracts/runner.contract.js";
 export { intenticContract } from "./contracts/intentic.contract.js";
 export { inventoryContract } from "./contracts/inventory.contract.js";
+export { issuesContract } from "./contracts/issues.contract.js";
 export { logsContract } from "./contracts/logs.contract.js";
 export { REQUEST_ID_EVIDENCE_ROUTE, REQUEST_ID_HEADER } from "./request-id.js";
 export { loopsContract } from "./contracts/loops.contract.js";
@@ -108,6 +110,7 @@ export * from "./agent-catalog.js";
 export * from "./agent-run-model.js";
 export * from "./capability-env.js";
 export * from "./command-classes.js";
+export * from "./credential-material.js";
 export * from "./capability-secrets.js";
 export * from "./conversation-ids.js";
 export * from "./documents.js";
@@ -151,6 +154,7 @@ export * from "./schemas/history.js";
 export * from "./schemas/hosts.js";
 export * from "./schemas/intentic.js";
 export * from "./schemas/inventory.js";
+export * from "./schemas/issues.js";
 export * from "./schemas/logs.js";
 export * from "./schemas/loops.js";
 export * from "./schemas/maintenance.js";
@@ -213,6 +217,7 @@ export const sandboxContract = {
     history: historyContract,
     workspace: workspaceContract,
     inventory: inventoryContract,
+    issues: issuesContract,
     logs: logsContract,
     loops: loopsContract,
     panels: panelsContract,

package/src/ingress-contract.test.ts

@@ -0,0 +1,65 @@
+import { generateKeyPairSync } from "node:crypto";
+import { describe, expect, it } from "vitest";
+import { hostOwnerId, mintReachabilityGrant, verifyReachabilityGrant } from "./ingress-contract.js";
+
+const pemPair = (): { privateKey: string; publicKey: string } => {
+    const { privateKey, publicKey } = generateKeyPairSync("ed25519");
+    return {
+        privateKey: privateKey.export({ type: "pkcs8", format: "pem" }).toString(),
+        publicKey: publicKey.export({ type: "spki", format: "pem" }).toString(),
+    };
+};
+
+const SANDBOX_ID = "abc123def456";
+
+describe("reachability grant", () => {
+    it("round-trips through mint and verify", () => {
+        const keys = pemPair();
+        const token = mintReachabilityGrant(keys.privateKey, SANDBOX_ID, 1_700_000_000_123);
+        expect(verifyReachabilityGrant(keys.publicKey, token)).toEqual({ sandboxId: SANDBOX_ID, issuedAt: 1_700_000_000 });
+    });
+
+    it("refuses a grant signed by another key", () => {
+        const token = mintReachabilityGrant(pemPair().privateKey, SANDBOX_ID, Date.now());
+        expect(verifyReachabilityGrant(pemPair().publicKey, token)).toBeUndefined();
+    });
+
+    it("refuses a tampered payload", () => {
+        const keys = pemPair();
+        const token = mintReachabilityGrant(keys.privateKey, SANDBOX_ID, Date.now());
+        const [prefix, , signature] = token.split(".");
+        const forged = Buffer.from(JSON.stringify({ sub: "000000000000", iat: 1 }), "utf8").toString("base64url");
+        expect(verifyReachabilityGrant(keys.publicKey, `${prefix}.${forged}.${signature}`)).toBeUndefined();
+    });
+
+    it("answers undefined for garbage rather than throwing", () => {
+        const keys = pemPair();
+        for (const junk of ["", "ig1", "ig1..", "nonsense.a.b", "ig2.a.b", "ig1.%%%.%%%"]) {
+            expect(verifyReachabilityGrant(keys.publicKey, junk)).toBeUndefined();
+        }
+    });
+
+    it("refuses to mint for something that is not a sandbox id", () => {
+        expect(() => mintReachabilityGrant(pemPair().privateKey, "not-an-id", Date.now())).toThrow(/12-hex/);
+    });
+});
+
+describe("hostOwnerId", () => {
+    it("owns the daemon's own name and every labelled name", () => {
+        expect(hostOwnerId(`sandbox-${SANDBOX_ID}.sbx.example.dev`)).toBe(SANDBOX_ID);
+        expect(hostOwnerId(`preview-operator-${SANDBOX_ID}.sbx.example.dev`)).toBe(SANDBOX_ID);
+        expect(hostOwnerId(`port-0f0f0f0f0f0f-${SANDBOX_ID}.sbx.example.dev`)).toBe(SANDBOX_ID);
+        expect(hostOwnerId(`public-1a2b3c4d5e6f-${SANDBOX_ID}.sbx.example.dev`)).toBe(SANDBOX_ID);
+    });
+
+    it("ignores a port suffix", () => {
+        expect(hostOwnerId(`sandbox-${SANDBOX_ID}.sbx.example.dev:443`)).toBe(SANDBOX_ID);
+    });
+
+    it("owns nothing that does not end in a 12-hex tail", () => {
+        // The ingress's own door, the zone apex, the loopback name's bare-id label, and a near-miss tail.
+        for (const host of ["ingress.sbx.example.dev", "sbx.example.dev", `${SANDBOX_ID}.local.sbx.example.dev`, "sandbox-abc123def45.sbx.example.dev", ""]) {
+            expect(hostOwnerId(host)).toBeUndefined();
+        }
+    });
+});

package/src/ingress-contract.ts

@@ -0,0 +1,155 @@
+import { createPrivateKey, createPublicKey, sign as edSign, verify as edVerify } from "node:crypto";
+
+/* THE INGRESS CONTRACT: how a sandbox is reached now that the reachability fabric is the platform's OWN edge
+ * (the `@intentic/ingress` app on Fly) instead of a zrok hub. Node-only (crypto), like ./tunnel-ids beside it;
+ * shared by the platform (mints grants), the ingress (verifies grants, routes hosts), and the daemon (dials
+ * the tunnel). The three MUST agree on every string in this file, which is why it exists.
+ *
+ * WHAT REPLACED WHAT. Under zrok, reachability was STATE: an account minted per sandbox over the hub's admin
+ * API, names claimed one by one, shares bound to them, and a reaper collecting what the soft-deletes leaked.
+ * Every piece of that state existed to answer one question — "which sandbox may serve this hostname?" — that
+ * the hostnames ALREADY answer by construction: every public name a sandbox serves ends in its own 12-hex id
+ * (`sandbox-<id>`, `preview-<panel>-<id>`, `port-<slot>-<id>`, `public-<slot>-<id>`; hostnames.ts is the
+ * single source). So ownership is a PARSE, not a registry, and the only thing that has to be minted is proof
+ * of identity: a grant, signed by the platform, saying "the bearer is sandbox <id>". Provisioning reachability
+ * becomes a pure function — no hub round trip, no row to cache a token on, no orphan to reconcile, and
+ * revoking it is deleting the sandbox row (the ingress asks the platform on register, below).
+ *
+ * THE FLOW. The daemon dials ONE outbound WebSocket to the ingress (INGRESS_TUNNEL_PATH) presenting its grant
+ * in INGRESS_GRANT_HEADER. The ingress verifies the signature offline, registers the tunnel under grant.sub,
+ * and from then on routes every edge request whose Host's leftmost label ends in `-<that id>` (or is exactly
+ * `sandbox-<id>`) down that tunnel. A second tunnel for the same id DISPLACES the first — the new container is
+ * by definition the live one, which is what buries the zrok-era stale-share reclaim dance (a recreated box
+ * used to fight the hub over names its dead predecessor still held; here the fight cannot exist).
+ *
+ * THE DATA PLANE over the tunnel is an HTTP/2 cleartext session runs over the WebSocket's binary stream:
+ * the ingress side opens an http2 CLIENT session over the duplex (node's http2.connect with createConnection),
+ * the daemon side feeds the duplex to an http2 SERVER session, and each edge request becomes one h2 stream
+ * with the original :authority preserved, which the daemon's client forwards to its own loopback listener
+ * (the Hono app already dispatches previews by Host). WebSocket upgrades ride CONNECT-method streams carrying
+ * the raw upgraded bytes. All of it is node core — the mux, flow control and per-stream backpressure are
+ * h2's own, not ours to reimplement. The implementation lives in ./ingress-protocol.ts (both halves, one
+ * owner); this file pins only what every party must agree on.
+ *
+ * WHY PER-REQUEST ROUTING IS NOT OPTIONAL: the edge terminates TLS under ONE wildcard certificate, and h2
+ * browsers coalesce connections across every hostname a certificate covers — one TCP connection can carry
+ * `sandbox-a…` and `preview-x-b…` interleaved. Routing a CONNECTION by its first Host would send one
+ * sandbox's requests to another. The unit of routing is the request (h2 stream), never the connection. */
+
+// ── The reachability grant ──────────────────────────────────────────────────────────────────────────────
+
+/* Version prefix, so a future shape can coexist during a key rotation. Not a negotiation: an ingress that
+ * does not know a prefix refuses the tunnel, and the box retries until its operator updates something. */
+const GRANT_PREFIX = "ig1";
+
+const base64url = (bytes: Buffer): string => bytes.toString("base64url");
+
+// The signed claim. `sub` is the sandbox's 12-hex id (sandboxIdFromToken in ./tunnel-ids); `iat` is seconds.
+// Deliberately no expiry: the grant lives in a container's env for the container's whole life, and the
+// revocation that matters (the sandbox being deleted) is answered by the platform on register, not by time.
+export interface ReachabilityGrant {
+    readonly sandboxId: string;
+    readonly issuedAt: number;
+}
+
+const SANDBOX_ID = /^[0-9a-f]{12}$/;
+
+/* Mint a grant: Ed25519 over the canonical payload bytes. Ed25519 because node signs/verifies it with key
+ * objects alone (no hash negotiation, no padding modes), signatures are 64 bytes, and the platform already
+ * depends on nothing for it — the private key is config (PEM, PKCS8), the public key rides the ingress env. */
+export const mintReachabilityGrant = (privateKeyPem: string, sandboxId: string, issuedAtMs: number): string => {
+    if (!SANDBOX_ID.test(sandboxId)) {
+        throw new Error(`a reachability grant names a 12-hex sandbox id, got "${sandboxId}"`);
+    }
+    const payload = Buffer.from(JSON.stringify({ sub: sandboxId, iat: Math.floor(issuedAtMs / 1000) }), "utf8");
+    const signature = edSign(null, payload, createPrivateKey(privateKeyPem));
+    return `${GRANT_PREFIX}.${base64url(payload)}.${base64url(signature)}`;
+};
+
+/* Verify a grant against the platform's public key. Every malformed shape answers undefined rather than
+ * throwing: this runs on the ingress's unauthenticated door, where a garbage token is weather, not a fault. */
+export const verifyReachabilityGrant = (publicKeyPem: string, token: string): ReachabilityGrant | undefined => {
+    const parts = token.split(".");
+    if (parts.length !== 3 || parts[0] !== GRANT_PREFIX) {
+        return undefined;
+    }
+    try {
+        const payload = Buffer.from(parts[1] as string, "base64url");
+        const signature = Buffer.from(parts[2] as string, "base64url");
+        if (!edVerify(null, payload, createPublicKey(publicKeyPem), signature)) {
+            return undefined;
+        }
+        const parsed = JSON.parse(payload.toString("utf8")) as { sub?: unknown; iat?: unknown };
+        if (typeof parsed.sub !== "string" || !SANDBOX_ID.test(parsed.sub) || typeof parsed.iat !== "number") {
+            return undefined;
+        }
+        return { sandboxId: parsed.sub, issuedAt: parsed.iat };
+    } catch {
+        return undefined;
+    }
+};
+
+// ── Host → owner routing ────────────────────────────────────────────────────────────────────────────────
+
+/* Which sandbox may serve this Host. The leftmost DNS label either IS `sandbox-<id>` or ends in `-<id>`
+ * (preview/port/public labels, hostnames.ts) — a fixed-length tail, so label keys containing `-` stay
+ * unambiguous. Anything else (the ingress's own name, the zone apex, a stray subdomain) answers undefined,
+ * which the ingress turns into its 404. The loopback name (`<id>.local.<zone>`) never reaches the ingress —
+ * it resolves to 127.0.0.1 — and its bare-id label deliberately does not match here. */
+export const hostOwnerId = (host: string): string | undefined => {
+    const label = host.split(":")[0]?.split(".")[0] ?? "";
+    const match = /-([0-9a-f]{12})$/.exec(label);
+    return match === null ? undefined : match[1];
+};
+
+// ── Wire constants ──────────────────────────────────────────────────────────────────────────────────────
+
+/* The tunnel door on the ingress. Versioned in the path so a v2 session shape is a new door, not a flag day:
+ * the ingress serves both for as long as old containers exist. Checked BEFORE host routing — the ingress's own
+ * hostname carries no sandbox id on purpose. */
+export const INGRESS_TUNNEL_PATH = "/tunnel/v1";
+
+// The grant rides a header on the tunnel upgrade (a Node client can set one; this is never a browser).
+export const INGRESS_GRANT_HEADER = "x-intentic-grant";
+
+/* The env vocabulary, every lane (connect one-liner, compose file, hosted machine env) hands the same pair
+ * down and the entrypoint/daemon read exactly these names. SANDBOX_PUBLIC_URL is unchanged from the zrok era
+ * and stays beside them. */
+export const ENV_INGRESS_URL = "INGRESS_URL";
+export const ENV_SANDBOX_GRANT = "SANDBOX_GRANT";
+
+// ── The daemon-side surface (pinned for the boot wiring) ────────────────────────────────────────────────
+
+/* The daemon-side tunnel behavior this contract requires. Dial, register, forward to the loopback listener,
+ * reconnect forever with backoff —
+ * the tunnel is the sandbox's reachability, so like the zrok agent's restart loop it never gives up, it only
+ * ever waits longer. close() is for shutdown and tests. */
+export interface IngressTunnelOptions {
+    // e.g. https://ingress.<zone>. The daemon derives the wss:// door itself (INGRESS_TUNNEL_PATH).
+    readonly url: string;
+    readonly grant: string;
+    // The daemon's own loopback listener; every h2 stream lands there as a plain HTTP/1.1 request or upgrade.
+    readonly targetPort: number;
+    readonly log: (message: string, error?: unknown) => void;
+}
+
+export interface IngressTunnelHandle {
+    readonly close: () => Promise<void>;
+    // For /health and the boot log: whether the tunnel currently holds a registered session.
+    readonly connected: () => boolean;
+}
+
+export type StartIngressTunnel = (options: IngressTunnelOptions) => IngressTunnelHandle;
+
+/* ── What the INGRESS side must also honor (spec, enforced by ingress-protocol tests) ──────────────────────
+ *
+ *  • Register: verify the grant offline; then, when PLATFORM_URL is configured, ask the platform whether the
+ *    sandbox still exists (GET /api/reachability/<id>, 200/404, answer cached; fail-OPEN on a platform that
+ *    does not answer — reachability must not depend on the platform being up, that is the whole point of the
+ *    platform being off the hot path). A 404 refuses the tunnel: that is revocation.
+ *  • Displacement: a new tunnel for an id closes the old session (code 4001) and takes the registration.
+ *  • Liveness: WebSocket ping every 15s; a peer silent for 45s is dead and unregistered.
+ *  • Routing: request host → hostOwnerId → registered tunnel; no tunnel answers 502 with a body naming the
+ *    sandbox label (the browser's availability flow reads any 5xx as "sandbox unreachable" and drives wake).
+ *  • The tunnel door itself (INGRESS_TUNNEL_PATH) and anything not carrying a sandbox-id host answer on the
+ *    ingress directly; they are never routed. */

package/src/routes.test.ts

@@ -77,7 +77,9 @@ describe(`routeShapes`, () => {
     it(`changes the fingerprint when a field is added`, () => {
         const before = routeShapes(shaped(z.object({ a: z.string() })))[`vpn.list`];
         const after = routeShapes(shaped(z.object({ a: z.string(), b: z.number() })))[`vpn.list`];
-        expect(before).toBeDefined();
+        // A fingerprint is a string, and saying so is what makes the line below mean something: with `before`
+        // undefined and `after` a real shape, "they differ" is true for the wrong reason.
+        expect(before).toEqual(expect.any(String));
         expect(after).not.toBe(before);
     });
 
@@ -99,7 +101,7 @@ describe(`routeShapes`, () => {
         const one = z.object({ a: z.string().default(`x`) });
         const asOutput = routeShapes(shaped(one))[`vpn.list`];
         const asInput = routeShapes({ vpn: { list: oc.route({ method: "GET", path: "/vpn" }).input(one) } })[`vpn.list`];
-        expect(asOutput).toBeDefined();
+        expect(asOutput).toEqual(expect.any(String));
         expect(asInput).not.toBe(asOutput);
     });
 

package/src/runtime-state.ts

@@ -69,6 +69,22 @@ const RUNTIME_DOMAINS = [
     // is why the daemon rate-limits this domain rather than pushing every mutation (see runtime-watch.ts).
     { domain: "subagents", invalidates: [["subagents"]] },
 
+    /* THE MACHINES ON THE OTHER END OF A SOCKET, three domains that are one story: the user's computers, the
+     * browsers holding the extension, and this sandbox's runners.
+     *
+     * Announced, and about as announced as a fact can be. "Online" here is not sampled, inferred or timed out
+     * of, it IS a socket in this process: the hub accepts one, replaces one, drops one on a failed heartbeat, or
+     * cuts one on a revoke, and those four moments are the entire set of ways the answer changes. Nothing on
+     * disk moves, no pane appears, and no other feed could carry it.
+     *
+     * They land on `capabilities` because a host or webext card's state is LITERALLY the hub's answer
+     * (handlers/host.ts: `hub.online(id) ? active : pending`), which is what a person watches while they paste a
+     * pairing command into a laptop. That wait is the whole reason these are here: it was three seconds of
+     * polling per card, running only because nobody had told the browser that the daemon already knew. */
+    { domain: "hosts", invalidates: [["capabilities"], ["computers"]] },
+    { domain: "webext", invalidates: [["capabilities"]] },
+    { domain: "runners", invalidates: [["runners"]] },
+
     /* The post queue, when the DAEMON moves it rather than the owner. Approving is the owner's own mutation and
      * refetches itself, but everything after that happens while nobody is touching the page: a held post coming
      * due, a Discord send landing, a publish turn writing back what went out. Those are the moments the row on

package/src/schemas/agent.ts

@@ -74,7 +74,7 @@ export type AgentOrigin = z.infer<typeof AgentOriginSchema>;
  * gate); never sent by a client. Chat and loops are absent deliberately: both begin with the owner's own
  * click, and holding the owner's work in their own queue is a queue entry that says nothing (the same argument
  * fireAutomation's `cleared` makes about a by-hand fire). */
-export const WakeSourceSchema = z.enum(["schedule", "event", "listener", "webchat", "workspace", "workflow"]);
+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"]);
@@ -96,7 +96,11 @@ export const CommandClassSchema = z.enum([
      * owner wrote no rule, which is why it is separate from files.destructive rather than a shade of it:
      * `rm -rf build` is ordinary work in a disposable container and `rm -rf /` is the end of the machine. */
     "system.destructive",
-    // Names credential material: a .env file, an ssh key, ~/.aws/credentials, .npmrc, a stored token file.
+    /* READS credential material: a `{{secret:NAME}}` reference (which becomes the value on the way into the
+     * process), or a file that actually holds one — a dotenv, a private key, ~/.aws/credentials, an npmrc.
+     * "Actually" is load-bearing and is checked rather than assumed where the caller can open the file: an
+     * npmrc with no token in it, a dotenv of ports, a public key, a path that is not there, are none of them
+     * this class, however much they look like it from the command line. See command-classes.ts. */
     "secrets.access",
     // Publishes outward and irreversibly: npm/pnpm/yarn/cargo publish, gh release create, docker push.
     "package.publish",
@@ -114,6 +118,15 @@ export const AdmissionPolicySchema = z.object({
     event: AdmissionRuleSchema.default("allow"),
     listener: AdmissionRuleSchema.default("allow"),
     webchat: AdmissionRuleSchema.default("allow"),
+    /* THE ONE SOURCE THAT HOLDS BY DEFAULT, and the exception is argued rather than assumed. A Front Desk wake
+     * runs the read-only Front Desk persona: a stranger drives the prompt and the toolbox is a shelf of two.
+     * A bug-report wake is the opposite on both counts, it is pointed at the repository with the powers to
+     * change it, and the brief is a stack trace and a sentence somebody else's browser wrote.
+     *
+     * Held is not blocked: the wake sits in the same approvals queue every other hold uses, with the issue's
+     * own title on the card, and one click runs it. An owner who wants their crashes fixed while they sleep
+     * sets this to `allow` deliberately, which is the direction that decision should have to be made in. */
+    issues: AdmissionRuleSchema.default("hold"),
     workspace: AdmissionRuleSchema.default("allow"),
     workflow: z.enum(["allow", "deny"]).default("allow"),
 });