hyperbrane 0.1.2 → 0.2.0

package/dist/portal-gateway/gatewayService.d.ts

@@ -1,41 +1,11 @@
-import { type DockerClient } from "../lib/docker.ts";
-import type { ManagedImage } from "../lib/image.ts";
-import { type Sandbox } from "../sandbox/api.ts";
-import { type Gateway, type GatewayCredential, type TrafficRule, type Upstream } from "./api.ts";
-import type { GatewayStorage } from "./gatewayStorage.ts";
-import type { PortalStorage } from "./portalStorage.ts";
-import type { PortalService } from "./portalService.ts";
+import type { Sandbox, SandboxDataEndpoint } from "../sandbox/api.ts";
+import { type GatewayClient } from "./api.ts";
+import { GATEWAY_STATE_PATH, gatewayCaCertificatePath, gatewayContainerName } from "./control.ts";
+export { GATEWAY_STATE_PATH, gatewayCaCertificatePath, gatewayContainerName };
 /** @sealed */
-export interface GatewayService {
-    createGateway(gateway: Gateway): Promise<Gateway>;
-    destroyGateway(gatewayName: string): Promise<void>;
-    listGateways(): Promise<Gateway[]>;
-    restartGateway(gatewayName: string): Promise<void>;
-    listCredentials(gatewayName: string): Promise<GatewayCredential[]>;
-    deleteCredential(gatewayName: string, credentialName: string): Promise<void>;
-    registerUpstream(gatewayName: string, upstream: Upstream): Promise<Upstream>;
-    listUpstreams(gatewayName: string): Promise<Upstream[]>;
-    removeUpstream(gatewayName: string, upstreamName: string): Promise<void>;
-    setApiKey(gatewayName: string, upstreamName: string, keyName: string, key: string): Promise<{
-        fake: string;
-    }>;
-    deleteApiKey(gatewayName: string, upstreamName: string, keyName: string): Promise<void>;
-    createTrafficRule(gatewayName: string, rule: TrafficRule): Promise<TrafficRule>;
-    updateTrafficRule(gatewayName: string, rule: TrafficRule): Promise<TrafficRule>;
-    deleteTrafficRule(gatewayName: string, ruleName: string): Promise<void>;
-    listTrafficRules(gatewayName: string): Promise<TrafficRule[]>;
-    trafficRuleRespond(gatewayName: string, ruleName: string, action: "ALLOW" | "DENY"): Promise<void>;
+export interface GatewayService extends GatewayClient {
 }
-/** Where the gateway's state directory is mounted in its container. */
-export declare const GATEWAY_STATE_PATH = "/state";
-export declare function gatewayContainerName(gatewayName: string): string;
-/** Host path of the CA that signs everything the gateway intercepts; dimensions behind it must trust it. */
-export declare function gatewayCaCertificatePath(stateDirectory: string): string;
 export declare function assertValidName(kind: string, name: string): void;
-/**
- * `host` is the machine the docker daemon runs on, rooted at "/" so the state directory (a
- * bind-mount source) resolves the same way docker resolves it.
- */
-export declare function createGatewayService(storage: GatewayStorage, portals: PortalStorage, docker: DockerClient, image: ManagedImage, host: Sandbox, 
-/** Re-wires the portals of a gateway whose container restarted or was replaced. */
-restoring?: Pick<PortalService, "restorePortals">): GatewayService;
+export declare function createGatewayService(host: Sandbox & SandboxDataEndpoint, { dataDirectory }?: {
+    dataDirectory?: string;
+}): GatewayService;

package/dist/portal-gateway/gatewayService.js

@@ -1,25 +1,11 @@
 import { isIPv4 } from "node:net";
-import { DockerError } from "../lib/docker.js";
+import { createDockerClient } from "../lib/docker.js";
+import { createGatewayImage } from "./image.js";
 import { InvalidNameError, checkName } from "../lib/jsonDirectory.js";
-import { SandboxNotFoundError } from "../sandbox/api.js";
-import { sleep } from "../lib/sleep.js";
-import { HYPERBRANE_VERSION } from "../lib/version.js";
-import { GatewayConflictError, GatewayInvalidError, GatewayNotFoundError, } from "./api.js";
-import { issueKeyFake } from "./fakes.js";
+import { GatewayInvalidError, GatewayNotFoundError } from "./api.js";
+import { GATEWAY_STATE_PATH, gatewayCaCertificatePath, gatewayContainerName, gatewayControl } from "./control.js";
 import { BUILTIN_UPSTREAMS } from "../upstreams/index.js";
-/** Where the gateway's state directory is mounted in its container. */
-export const GATEWAY_STATE_PATH = "/state";
-const PROXY_PORT = 8080;
-const DNS_PORT = 5353;
-const READY_TIMEOUT_MS = 60_000;
-// "hybgw-" can't collide with a dimension's "hyb-<name>": dimension names start with a letter or digit.
-export function gatewayContainerName(gatewayName) {
-    return `hybgw-${gatewayName}`;
-}
-/** Host path of the CA that signs everything the gateway intercepts; dimensions behind it must trust it. */
-export function gatewayCaCertificatePath(stateDirectory) {
-    return `${stateDirectory}/mitmproxy/mitmproxy-ca-cert.pem`;
-}
+export { GATEWAY_STATE_PATH, gatewayCaCertificatePath, gatewayContainerName };
 export function assertValidName(kind, name) {
     try {
         checkName(name);
@@ -30,176 +16,51 @@ export function assertValidName(kind, name) {
         throw error;
     }
 }
-/**
- * `host` is the machine the docker daemon runs on, rooted at "/" so the state directory (a
- * bind-mount source) resolves the same way docker resolves it.
- */
-export function createGatewayService(storage, portals, docker, image, host, 
-/** Re-wires the portals of a gateway whose container restarted or was replaced. */
-restoring) {
-    // Keeps no state between calls: the record is written first so a slow or crashed create stays
-    // visible, and every later step checks before it acts, so re-running converges.
+const FAKE_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
+function endpointName(gatewayName) {
+    return `gateway-${gatewayName}`;
+}
+export function createGatewayService(host, { dataDirectory } = {}) {
+    const control = gatewayControl(host, () => createGatewayImage(createDockerClient(host)).ensure(), { dataDirectory });
     async function createGateway(gateway) {
         assertValidName("gateway", gateway.name);
         const upstreams = (gateway.upstreams ?? BUILTIN_UPSTREAMS).map(validUpstream);
-        const name = gatewayContainerName(gateway.name);
-        const existing = await docker.inspectContainer(name);
-        if (existing)
-            assertOwnedContainer(existing, gateway.name);
-        const record = await storage.insertGateway({ name: gateway.name, state: "creating" });
-        const stateDirectory = await storage.ensureStateDirectory(gateway.name);
-        for (const upstream of upstreams)
-            await storage.saveUpstream(gateway.name, upstream);
-        const imageTag = await image.ensure();
-        await ensureContainer(gateway.name, stateDirectory, imageTag);
-        await docker.startContainer(name);
-        await awaitReady(gateway.name, stateDirectory);
-        if (record.state !== "ready")
-            await storage.saveGateway({ name: gateway.name, state: "ready" });
-        // A replaced container (an older image's) came without them; still wired, this is one look.
-        await restoring?.restorePortals({ gatewayName: gateway.name });
+        await control.createGateway(gateway.name, upstreams);
+        await control.startTransport(gateway.name, await host.openEndpoint(endpointName(gateway.name)), { restart: false });
         return { name: gateway.name };
     }
-    // A container from an older image is replaced: everything worth keeping (CA, credentials, rules)
-    // is in the mounted state directory. createGateway re-wires its portals once it's ready.
-    async function ensureContainer(gatewayName, stateDirectory, imageTag) {
-        const name = gatewayContainerName(gatewayName);
-        const existing = await docker.inspectContainer(name);
-        if (existing) {
-            assertOwnedContainer(existing, gatewayName);
-            if (existing.Config?.Image === imageTag)
-                return;
-            await docker.removeContainer(name);
-        }
-        try {
-            await docker.createContainer(name, {
-                Image: imageTag,
-                Hostname: name,
-                Labels: {
-                    hyperbrane: "true",
-                    "hyperbrane.version": HYPERBRANE_VERSION,
-                    "hyperbrane.gateway": gatewayName,
-                },
-                HostConfig: {
-                    // A mount, not a copy: rules and credentials written by the service take effect on the next
-                    // request, and the CA survives the container being recreated.
-                    Binds: [`${stateDirectory}:${GATEWAY_STATE_PATH}`],
-                    CapAdd: ["NET_ADMIN"],
-                    NetworkMode: "bridge",
-                    Init: true,
-                    RestartPolicy: { Name: "unless-stopped" },
-                },
-            });
-        }
-        catch (error) {
-            // Lost a race with another creator: fine as long as the winner is ours.
-            if (!(error instanceof DockerError && error.status === 409))
-                throw error;
-            assertOwnedContainer(await awaitContainer(name, error), gatewayName);
-        }
-    }
-    // Docker reserves the name before the winner's container becomes inspectable, so give it a moment.
-    async function awaitContainer(name, conflict) {
-        for (let attempt = 0; attempt < 50; attempt++) {
-            const container = await docker.inspectContainer(name);
-            if (container)
-                return container;
-            await sleep(100);
-        }
-        throw conflict;
-    }
-    // Ready = the proxy and its resolver are listening (so the redirect rules are in, and nothing
-    // through a portal is refused) and the CA exists (so portals can install it into dimensions).
-    async function awaitReady(gatewayName, stateDirectory) {
-        const name = gatewayContainerName(gatewayName);
-        const deadline = Date.now() + READY_TIMEOUT_MS;
-        while (Date.now() < deadline) {
-            if ((await proxyListening(name)) && (await exists(gatewayCaCertificatePath(stateDirectory))))
-                return;
-            await sleep(250);
-        }
-        const state = (await docker.inspectContainer(name))?.State;
-        throw new Error(`gateway ${gatewayName} did not become ready: container ${state?.Status ?? "missing"}, exit code ${state?.ExitCode ?? "-"}`);
-    }
-    async function proxyListening(name) {
-        try {
-            const result = await docker.exec(name, { cmd: ["ss", "-Hln", `( sport = :${PROXY_PORT} or sport = :${DNS_PORT} )`], user: "root" });
-            // Both: TCP for the proxy, UDP for the resolver.
-            return result.exitCode === 0 && /^tcp\b/m.test(result.stdout) && /^udp\b/m.test(result.stdout);
-        }
-        catch (error) {
-            // Not running (yet, or restarting after a failed start).
-            if (error instanceof DockerError && error.status === 409)
-                return false;
-            throw error;
-        }
-    }
-    async function exists(path) {
-        try {
-            await host.stat(path);
-            return true;
-        }
-        catch (error) {
-            if (error instanceof SandboxNotFoundError)
-                return false;
-            throw error;
-        }
-    }
-    // Container first: if this crashes before the record is removed, the gateway still shows up and
-    // the destroy can be retried. Its state (credentials included) goes with the record.
     async function destroyGateway(gatewayName) {
         assertValidName("gateway", gatewayName);
-        const attached = (await portals.listPortals()).filter((portal) => portal.gatewayName === gatewayName);
-        if (attached.length > 0) {
-            throw new GatewayConflictError(`gateway ${gatewayName} still has portals: ${attached.map((portal) => portal.name).join(", ")}`);
-        }
-        const name = gatewayContainerName(gatewayName);
-        const existing = await docker.inspectContainer(name);
-        if (existing) {
-            assertOwnedContainer(existing, gatewayName);
-            await docker.removeContainer(name);
-        }
-        await storage.removeGateway(gatewayName);
+        await control.destroyGateway(gatewayName);
+        await host.closeEndpoint(endpointName(gatewayName));
     }
     async function restartGateway(gatewayName) {
-        const record = await requireGateway(gatewayName);
-        const name = gatewayContainerName(gatewayName);
-        const container = await docker.inspectContainer(name);
-        if (!container)
-            throw new GatewayNotFoundError(`gateway ${gatewayName} has no container; create it again`);
-        assertOwnedContainer(container, gatewayName);
-        await docker.restartContainer(name);
-        await awaitReady(gatewayName, await storage.ensureStateDirectory(record.name));
-        // The restart took its end of every portal with its network namespace.
-        await restoring?.restorePortals({ gatewayName });
+        assertValidName("gateway", gatewayName);
+        await control.restartGateway(gatewayName);
+        await control.startTransport(gatewayName, await host.openEndpoint(endpointName(gatewayName)), { restart: true });
     }
-    async function listGateways() {
-        return (await storage.listGateways()).map(({ name }) => ({ name }));
+    async function endpoint(gatewayName, options) {
+        assertValidName("gateway", gatewayName);
+        const name = endpointName(gatewayName);
+        const found = (await host.listEndpoints()).find((candidate) => candidate.name === name);
+        if (!found)
+            throw new GatewayNotFoundError(`gateway ${gatewayName} has no data endpoint; create it again`);
+        return { url: found.url, credentials: await host.credentials(name, options) };
     }
     async function listCredentials(gatewayName) {
-        await requireGateway(gatewayName);
-        // All of them at once: a read per upstream adds up on a remote machine.
-        const [upstreams, held] = await Promise.all([storage.listUpstreams(gatewayName), storage.listCredentials(gatewayName)]);
-        const credentials = [];
-        for (const upstream of upstreams) {
-            if (held.get(`${upstream.name}.oauth`))
-                credentials.push({ name: `${upstream.name}.oauth`, gatewayName, type: "oauth" });
-            const apiKeys = held.get(`${upstream.name}.api-keys`);
-            for (const [keyName, { fake }] of Object.entries(apiKeys?.keys ?? {})) {
-                credentials.push({ name: `${upstream.name}.key.${keyName}`, gatewayName, type: "apiKey", fake });
-            }
-        }
-        return credentials;
+        assertValidName("gateway", gatewayName);
+        return (await control.listCredentials(gatewayName)).flatMap(({ upstream, oauth, apiKeys }) => [
+            ...(oauth ? [{ name: `${upstream}.oauth`, gatewayName, type: "oauth" }] : []),
+            ...Object.entries(apiKeys?.keys ?? {}).map(([keyName, { fake }]) => ({ name: `${upstream}.key.${keyName}`, gatewayName, type: "apiKey", fake })),
+        ]);
     }
-    // Storage holds the only copy of a secret, and the gateway re-reads credentials per request. Without
-    // its OAuth credential, the upstream's next sign-in goes to the upstream again (switching accounts).
     async function deleteCredential(gatewayName, credentialName) {
         assertValidName("gateway", gatewayName);
         const keyAt = credentialName.indexOf(".key.");
         if (credentialName.endsWith(".oauth")) {
             const upstreamName = credentialName.slice(0, -".oauth".length);
             assertValidName("upstream", upstreamName);
-            await storage.removeOAuthCredential(gatewayName, upstreamName);
+            await control.removeOAuthCredential(gatewayName, upstreamName);
         }
         else if (keyAt > 0) {
             await deleteApiKey(gatewayName, credentialName.slice(0, keyAt), credentialName.slice(keyAt + ".key.".length));
@@ -209,124 +70,84 @@ restoring) {
         }
     }
     async function registerUpstream(gatewayName, upstream) {
-        await requireGateway(gatewayName);
+        assertValidName("gateway", gatewayName);
         const definition = validUpstream(upstream);
-        await storage.saveUpstream(gatewayName, definition);
+        await control.registerUpstream(gatewayName, definition);
         return definition;
     }
     async function listUpstreams(gatewayName) {
-        await requireGateway(gatewayName);
-        return (await storage.listUpstreams(gatewayName)).sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+        assertValidName("gateway", gatewayName);
+        return (await control.listUpstreams(gatewayName)).sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
     }
     async function removeUpstream(gatewayName, upstreamName) {
         assertValidName("gateway", gatewayName);
         assertValidName("upstream", upstreamName);
-        await storage.removeUpstream(gatewayName, upstreamName);
+        await control.removeUpstream(gatewayName, upstreamName);
     }
-    // A key keeps its fake when replaced, so dimensions already holding it keep working.
     async function setApiKey(gatewayName, upstreamName, keyName, key) {
-        const mode = (await requireUpstream(gatewayName, upstreamName)).modes.apiKey;
-        if (!mode)
-            throw new GatewayInvalidError(`upstream ${upstreamName} has no API key mode`);
+        assertValidName("gateway", gatewayName);
+        assertValidName("upstream", upstreamName);
         assertValidName("API key", keyName);
         if (typeof key !== "string" || key === "")
             throw new GatewayInvalidError("the API key is empty");
-        const stored = (await storage.readApiKeys(gatewayName, upstreamName)) ?? { keys: {} };
-        const fake = stored.keys[keyName]?.fake ?? issueKeyFake(mode.fake, key);
-        await storage.saveApiKeys(gatewayName, upstreamName, { keys: { ...stored.keys, [keyName]: { key, fake } } });
-        return { fake };
+        const bytes = crypto.getRandomValues(new Uint8Array(key.length + 16));
+        const characters = Array.from(bytes, (byte) => FAKE_ALPHABET[byte % FAKE_ALPHABET.length]).join("");
+        return { fake: await control.setApiKey(gatewayName, upstreamName, keyName, key, characters) };
     }
     async function deleteApiKey(gatewayName, upstreamName, keyName) {
-        await requireUpstream(gatewayName, upstreamName);
+        assertValidName("gateway", gatewayName);
+        assertValidName("upstream", upstreamName);
         assertValidName("API key", keyName);
-        const stored = await storage.readApiKeys(gatewayName, upstreamName);
-        if (!stored?.keys[keyName])
-            return;
-        const { [keyName]: _removed, ...keys } = stored.keys;
-        if (Object.keys(keys).length === 0)
-            await storage.removeApiKeys(gatewayName, upstreamName);
-        else
-            await storage.saveApiKeys(gatewayName, upstreamName, { keys });
+        await control.deleteApiKey(gatewayName, upstreamName, keyName);
     }
     async function createTrafficRule(gatewayName, rule) {
-        await requireGateway(gatewayName);
+        assertValidName("gateway", gatewayName);
         const requested = validTrafficRule(rule);
-        const stored = await storage.insertTrafficRule(gatewayName, requested);
-        if (!sameTrafficRule(stored, requested)) {
-            throw new GatewayConflictError(`traffic rule ${rule.name} already exists with a different spec`);
-        }
+        await control.createTrafficRule(gatewayName, requested);
         return requested;
     }
     async function updateTrafficRule(gatewayName, rule) {
-        await requireGateway(gatewayName);
+        assertValidName("gateway", gatewayName);
         const requested = validTrafficRule(rule);
-        await requireTrafficRule(gatewayName, rule.name);
-        await storage.saveTrafficRule(gatewayName, requested);
+        await control.updateTrafficRule(gatewayName, requested);
         return requested;
     }
-    // Requests an ASK rule is holding carry on once it's gone.
     async function deleteTrafficRule(gatewayName, ruleName) {
         assertValidName("gateway", gatewayName);
         assertValidName("traffic rule", ruleName);
-        await storage.removeTrafficRule(gatewayName, ruleName);
+        await control.deleteTrafficRule(gatewayName, ruleName);
     }
     async function listTrafficRules(gatewayName) {
-        await requireGateway(gatewayName);
-        const rules = await storage.listTrafficRules(gatewayName);
-        return rules.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+        assertValidName("gateway", gatewayName);
+        return (await control.listTrafficRules(gatewayName)).sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
     }
-    // Answers every request the rule is holding right now; later requests wait for a later answer.
     async function trafficRuleRespond(gatewayName, ruleName, action) {
-        await requireGateway(gatewayName);
-        if (action !== "ALLOW" && action !== "DENY")
-            throw new GatewayInvalidError(`invalid response: ${action}`);
-        const rule = await requireTrafficRule(gatewayName, ruleName);
-        if (rule.action !== "ASK")
-            throw new GatewayInvalidError(`traffic rule ${ruleName} is not an ASK rule`);
-        await storage.saveTrafficRuleResponse(gatewayName, { name: ruleName, action, at: Date.now() });
-    }
-    async function requireGateway(gatewayName) {
         assertValidName("gateway", gatewayName);
-        const record = await storage.readGateway(gatewayName);
-        if (!record)
-            throw new GatewayNotFoundError(`gateway ${gatewayName} does not exist`);
-        return record;
-    }
-    async function requireUpstream(gatewayName, upstreamName) {
-        await requireGateway(gatewayName);
-        assertValidName("upstream", upstreamName);
-        const upstream = await storage.readUpstream(gatewayName, upstreamName);
-        if (!upstream)
-            throw new GatewayNotFoundError(`upstream ${upstreamName} does not exist on gateway ${gatewayName}`);
-        return upstream;
-    }
-    async function requireTrafficRule(gatewayName, ruleName) {
         assertValidName("traffic rule", ruleName);
-        const rule = await storage.readTrafficRule(gatewayName, ruleName);
-        if (!rule)
-            throw new GatewayNotFoundError(`traffic rule ${ruleName} does not exist on gateway ${gatewayName}`);
-        return rule;
+        if (action !== "ALLOW" && action !== "DENY")
+            throw new GatewayInvalidError(`invalid response: ${action}`);
+        await control.trafficRuleRespond(gatewayName, ruleName, action);
     }
     return {
-        createGateway,
-        destroyGateway,
-        listGateways,
-        restartGateway,
+        createGateway: (gateway) => createGateway(gateway),
+        destroyGateway: (gatewayName) => destroyGateway(gatewayName),
+        listGateways: () => control.listGateways(),
+        restartGateway: (gatewayName) => restartGateway(gatewayName),
+        endpoint,
         listCredentials,
-        deleteCredential,
-        registerUpstream,
+        deleteCredential: (gatewayName, credentialName) => deleteCredential(gatewayName, credentialName),
+        registerUpstream: (gatewayName, upstream) => registerUpstream(gatewayName, upstream),
         listUpstreams,
-        removeUpstream,
-        setApiKey,
-        deleteApiKey,
-        createTrafficRule,
-        updateTrafficRule,
-        deleteTrafficRule,
+        removeUpstream: (gatewayName, upstreamName) => removeUpstream(gatewayName, upstreamName),
+        setApiKey: (gatewayName, upstreamName, keyName, key) => setApiKey(gatewayName, upstreamName, keyName, key),
+        deleteApiKey: (gatewayName, upstreamName, keyName) => deleteApiKey(gatewayName, upstreamName, keyName),
+        createTrafficRule: (gatewayName, rule) => createTrafficRule(gatewayName, rule),
+        updateTrafficRule: (gatewayName, rule) => updateTrafficRule(gatewayName, rule),
+        deleteTrafficRule: (gatewayName, ruleName) => deleteTrafficRule(gatewayName, ruleName),
         listTrafficRules,
-        trafficRuleRespond,
+        trafficRuleRespond: (gatewayName, ruleName, action) => trafficRuleRespond(gatewayName, ruleName, action),
     };
 }
-/** The checks the gateway relies on; the rest of the shape is the SDK client's (see upstream.ts). */
 function validUpstream(upstream) {
     assertValidName("upstream", upstream.name);
     const { oauth, apiKey, forced } = upstream.modes ?? {};
@@ -349,7 +170,6 @@ function validUpstream(upstream) {
         throw new GatewayInvalidError(`upstream ${upstream.name}: apiKey needs a fake shape`);
     return upstream;
 }
-/** Returns just the rule's fields, so nothing unknown ends up in storage. */
 function validTrafficRule(rule) {
     assertValidName("traffic rule", rule.name);
     if (typeof rule.urlMask !== "string" || rule.urlMask === "") {
@@ -368,7 +188,6 @@ function validTrafficRule(rule) {
     return { name: rule.name, urlMask: rule.urlMask, action: rule.action, delayMs: rule.delayMs };
 }
 const TCP_SCHEME = "tcp://";
-/** "tcp://<address>:<port>": address is "*", an IPv4 address or a CIDR; port is "*" or a number. */
 function assertValidTcpMask(ruleName, urlMask) {
     const target = urlMask.slice(TCP_SCHEME.length);
     const separator = target.lastIndexOf(":");
@@ -385,8 +204,3 @@ function assertValidTcpMask(ruleName, urlMask) {
 function sameTrafficRule(a, b) {
     return a.urlMask === b.urlMask && a.action === b.action && a.delayMs === b.delayMs;
 }
-function assertOwnedContainer(container, gatewayName) {
-    if (container.Config?.Labels?.["hyperbrane.gateway"] !== gatewayName) {
-        throw new GatewayConflictError(`container ${gatewayContainerName(gatewayName)} exists but is not managed by hyperbrane`);
-    }
-}

package/dist/portal-gateway/image.d.ts

@@ -1,6 +1,5 @@
 import type { DockerClient } from "../lib/docker.ts";
 import { type ManagedImage } from "../lib/image.ts";
-/** Bump whenever anything under ./image changes (and run `bun run embed:images`). */
 export declare const GATEWAY_IMAGE_VERSION = "v17";
 export declare const GATEWAY_IMAGE_REPOSITORY = "hyperbrane-gateway";
 export declare function createGatewayImage(docker: DockerClient): ManagedImage;

package/dist/portal-gateway/image.js

@@ -1,7 +1,5 @@
 import { createManagedImage } from "../lib/image.js";
-// The files under ./image, as strings (see dimension/image.ts).
 import { IMAGE_FILES } from "./imageFiles.generated.js";
-/** Bump whenever anything under ./image changes (and run `bun run embed:images`). */
 export const GATEWAY_IMAGE_VERSION = "v17";
 export const GATEWAY_IMAGE_REPOSITORY = "hyperbrane-gateway";
 export function createGatewayImage(docker) {

package/dist/portal-gateway/imageFiles.generated.js

@@ -1,8 +1,8 @@
 // Generated by scripts/embed-image-files.ts from portal-gateway/image/ — do not edit; run `bun run embed:images`.
 export const IMAGE_FILES = {
     "Dockerfile": "FROM debian:13-slim\nRUN apt-get update \\\n && apt-get install -y --no-install-recommends bash sudo git jq ca-certificates iproute2 nftables python3 python3-venv \\\n && python3 -m venv /opt/mitmproxy \\\n && /opt/mitmproxy/bin/pip install --no-cache-dir mitmproxy \\\n && ln -s /opt/mitmproxy/bin/mitmdump /usr/local/bin/mitmdump \\\n && mitmdump --version \\\n && rm -rf /var/lib/apt/lists/*\nCOPY entry.sh /usr/local/bin/hyb-gateway\nCOPY wire-portal.sh /usr/local/bin/hyb-wire-portal\nCOPY traffic_rules.py /opt/hyperbrane/traffic_rules.py\nCOPY upstreams.py /opt/hyperbrane/upstreams.py\nRUN chmod 0755 /usr/local/bin/hyb-gateway /usr/local/bin/hyb-wire-portal\nCMD [\"hyb-gateway\"]\n",
-    "entry.sh": "#!/bin/sh\n# Gateway container entry: redirects everything arriving over a portal into mitmproxy, then becomes\n# mitmproxy. If the redirect can't be installed, or mitmproxy exits, the container exits: a gateway\n# that isn't intercepting must not look healthy.\nset -eu\n\nSTATE=/state\nPROXY_PORT=8080\nDNS_PORT=5353\n\n# Portals end in \"hvg*\" interfaces. All TCP goes to the transparent proxy and DNS to its resolver;\n# nothing is forwarded, so there is no path out that bypasses mitmproxy. mitmproxy's own upstream\n# connections are locally generated and never pass PREROUTING, so it doesn't intercept itself.\nnft -f - <<EOF\ntable ip hyperbrane\ndelete table ip hyperbrane\ntable ip hyperbrane {\n  chain prerouting {\n    type nat hook prerouting priority dstnat; policy accept;\n    iifname \"hvg*\" meta l4proto tcp redirect to :$PROXY_PORT\n    iifname \"hvg*\" udp dport 53 redirect to :$DNS_PORT\n  }\n  chain input {\n    type filter hook input priority filter; policy accept;\n    iifname \"hvg*\" tcp dport $PROXY_PORT accept\n    iifname \"hvg*\" udp dport $DNS_PORT accept\n    iifname \"hvg*\" drop\n  }\n  chain forward {\n    type filter hook forward priority filter; policy accept;\n    iifname \"hvg*\" drop\n  }\n}\nEOF\n\n# An exit code of 0 is not proof: read the rules back.\nrules=\"$(nft list table ip hyperbrane)\"\ncase \"$rules\" in\n  *\"redirect to :$PROXY_PORT\"*\"redirect to :$DNS_PORT\"*) ;;\n  *) echo \"gateway: redirect rules are not installed\" >&2; exit 1 ;;\nesac\n\n# mitmproxy runs as the owner of the state directory, so everything it writes there (the CA) stays\n# readable and removable by the host service.\nowner_uid=\"$(stat -c %u \"$STATE\")\"\nowner_gid=\"$(stat -c %g \"$STATE\")\"\nexport HOME=/tmp\n# Eager: connect upstream as soon as the client connects, or protocols where the server speaks first\n# (SSH, SMTP) wait forever for a client that is waiting for them.\nexec setpriv --reuid=\"$owner_uid\" --regid=\"$owner_gid\" --clear-groups -- \\\n  mitmdump \\\n  --mode \"transparent@$PROXY_PORT\" \\\n  --mode \"dns@$DNS_PORT\" \\\n  --set \"confdir=$STATE/mitmproxy\" \\\n  --set connection_strategy=eager \\\n  -s /opt/hyperbrane/traffic_rules.py \\\n  -s /opt/hyperbrane/upstreams.py\n",
-    "wire-portal.sh": "#!/bin/sh\n# Wires a portal: a veth pair with one end in the dimension's network namespace and the other in the\n# gateway's, and a default route down it. A dimension with several portals has one default route per\n# portal; the lowest ROUTE_METRIC wins, and when its veth goes away (its gateway stopped) so does the\n# route, so traffic falls over to the next portal.\n# Runs in a privileged helper container sharing the host's network and pid namespaces, with the\n# host's /run at /hostrun.\n#\n# Inputs: PORTAL, DIMENSION_PID, GATEWAY_PID, DIMENSION_IF, GATEWAY_IF, DIMENSION_IP, GATEWAY_IP,\n# ROUTE_METRIC.\n# Safe to re-run: an already correct wiring is left alone, anything else is torn down and rebuilt.\nset -eu\n\n# Concurrent wirings of one portal would delete each other's veths; the lock lives on the host so it\n# is shared by every helper container.\nexec 9>\"/hostrun/hyperbrane-portal-$PORTAL.lock\"\nflock -w 30 9 || { echo \"timed out waiting for the wiring lock of $PORTAL\" >&2; exit 1; }\n\nmkdir -p /var/run/netns\nln -sf \"/proc/$DIMENSION_PID/ns/net\" /var/run/netns/dimension\nln -sf \"/proc/$GATEWAY_PID/ns/net\" /var/run/netns/gateway\ntrap 'rm -f /var/run/netns/dimension /var/run/netns/gateway' EXIT\n\nwired() {\n  ip -n dimension addr show dev \"$DIMENSION_IF\" 2>/dev/null | grep -q \"inet $DIMENSION_IP/30\" \\\n    && ip -n dimension route show default 2>/dev/null | grep -q \"via $GATEWAY_IP dev $DIMENSION_IF metric $ROUTE_METRIC\" \\\n    && ip -n gateway addr show dev \"$GATEWAY_IF\" 2>/dev/null | grep -q \"inet $GATEWAY_IP/30\"\n}\nwired && exit 0\n\n# A stale end can be in either namespace, or left on the host when a container died mid-wiring.\nip -n dimension link del \"$DIMENSION_IF\" 2>/dev/null || true\nip -n gateway link del \"$GATEWAY_IF\" 2>/dev/null || true\nip link del \"$DIMENSION_IF\" 2>/dev/null || true\nip link del \"$GATEWAY_IF\" 2>/dev/null || true\n\nip link add \"$DIMENSION_IF\" type veth peer name \"$GATEWAY_IF\"\nip link set \"$DIMENSION_IF\" netns dimension\nip link set \"$GATEWAY_IF\" netns gateway\nip -n dimension addr replace \"$DIMENSION_IP/30\" dev \"$DIMENSION_IF\"\nip -n dimension link set \"$DIMENSION_IF\" up\nip -n gateway addr replace \"$GATEWAY_IP/30\" dev \"$GATEWAY_IF\"\nip -n gateway link set \"$GATEWAY_IF\" up\nip -n dimension route replace default via \"$GATEWAY_IP\" dev \"$DIMENSION_IF\" metric \"$ROUTE_METRIC\"\n",
+    "entry.sh": "#!/bin/sh\nset -eu\n\nSTATE=/state\nPROXY_PORT=8080\nDNS_PORT=5353\n\nnft -f - <<EOF\ntable ip hyperbrane\ndelete table ip hyperbrane\ntable ip hyperbrane {\n  chain prerouting {\n    type nat hook prerouting priority dstnat; policy accept;\n    iifname \"hvg*\" meta l4proto tcp redirect to :$PROXY_PORT\n    iifname \"hvg*\" udp dport 53 redirect to :$DNS_PORT\n  }\n  chain input {\n    type filter hook input priority filter; policy accept;\n    iifname \"hvg*\" tcp dport $PROXY_PORT accept\n    iifname \"hvg*\" udp dport $DNS_PORT accept\n    iifname \"hvg*\" drop\n  }\n  chain forward {\n    type filter hook forward priority filter; policy accept;\n    iifname \"hvg*\" drop\n  }\n}\nEOF\n\nrules=\"$(nft list table ip hyperbrane)\"\ncase \"$rules\" in\n  *\"redirect to :$PROXY_PORT\"*\"redirect to :$DNS_PORT\"*) ;;\n  *) echo \"gateway: redirect rules are not installed\" >&2; exit 1 ;;\nesac\n\nowner_uid=\"$(stat -c %u \"$STATE\")\"\nowner_gid=\"$(stat -c %g \"$STATE\")\"\nexport HOME=/tmp\nexec setpriv --reuid=\"$owner_uid\" --regid=\"$owner_gid\" --clear-groups -- \\\n  mitmdump \\\n  --mode \"transparent@$PROXY_PORT\" \\\n  --mode \"dns@$DNS_PORT\" \\\n  --set \"confdir=$STATE/mitmproxy\" \\\n  --set connection_strategy=eager \\\n  -s /opt/hyperbrane/traffic_rules.py \\\n  -s /opt/hyperbrane/upstreams.py\n",
+    "wire-portal.sh": "#!/bin/sh\nset -eu\n\nexec 9>\"/hostrun/hyperbrane-portal-$PORTAL.lock\"\nflock -w 30 9 || { echo \"timed out waiting for the wiring lock of $PORTAL\" >&2; exit 1; }\n\nmkdir -p /var/run/netns\nln -sf \"/proc/$DIMENSION_PID/ns/net\" /var/run/netns/dimension\nln -sf \"/proc/$GATEWAY_PID/ns/net\" /var/run/netns/gateway\ntrap 'rm -f /var/run/netns/dimension /var/run/netns/gateway' EXIT\n\nwired() {\n  ip -n dimension addr show dev \"$DIMENSION_IF\" 2>/dev/null | grep -q \"inet $DIMENSION_IP/30\" \\\n    && ip -n dimension route show default 2>/dev/null | grep -q \"via $GATEWAY_IP dev $DIMENSION_IF metric $ROUTE_METRIC\" \\\n    && ip -n gateway addr show dev \"$GATEWAY_IF\" 2>/dev/null | grep -q \"inet $GATEWAY_IP/30\"\n}\nwired && exit 0\n\nip -n dimension link del \"$DIMENSION_IF\" 2>/dev/null || true\nip -n gateway link del \"$GATEWAY_IF\" 2>/dev/null || true\nip link del \"$DIMENSION_IF\" 2>/dev/null || true\nip link del \"$GATEWAY_IF\" 2>/dev/null || true\n\nip link add \"$DIMENSION_IF\" type veth peer name \"$GATEWAY_IF\"\nip link set \"$DIMENSION_IF\" netns dimension\nip link set \"$GATEWAY_IF\" netns gateway\nip -n dimension addr replace \"$DIMENSION_IP/30\" dev \"$DIMENSION_IF\"\nip -n dimension link set \"$DIMENSION_IF\" up\nip -n gateway addr replace \"$GATEWAY_IP/30\" dev \"$GATEWAY_IF\"\nip -n gateway link set \"$GATEWAY_IF\" up\nip -n dimension route replace default via \"$GATEWAY_IP\" dev \"$DIMENSION_IF\" metric \"$ROUTE_METRIC\"\n",
     "traffic_rules.py": "# mitmproxy addon applying the gateway's traffic rules to everything arriving through a portal.\n#\n# Rules are the JSON files the gateway service writes to /state/traffic-rules, re-read every time, so\n# a change takes effect without a reload. A rule's urlMask is a glob, and its scheme says what it\n# applies to:\n#   tcp://<address>:<port>  every TCP connection, by its destination, before it is made upstream.\n#                           address is \"*\", an IPv4 address or a CIDR; port is \"*\" or a number.\n#                           Hostnames aren't known at that point, so rules don't use them.\n#   anything else           every HTTP(S) request, matched as a glob against host:port/path?query.\n#                           The scheme doesn't matter (http, https or none match the same), and a\n#                           mask without a port matches any port, one without a path any path:\n#                           \"github.com\" is the whole host, \"github.com:80/*\" only its plain HTTP.\n# Rules are checked in name order and the first match decides:\n#   BLOCK  refuse: a 403 for a request, a closed connection for TCP\n#   DELAY  hold for delayMs, then carry on\n#   ASK    hold until the service records an answer for the rule in /state/traffic-responses (only\n#          answers given after the hold began count); DENY refuses, ALLOW carries on\n\nimport asyncio\nimport fnmatch\nimport ipaddress\nimport json\nimport os\nimport time\n\nfrom mitmproxy import http\nfrom mitmproxy.proxy import server_hooks\n\nSTATE = \"/state\"\nRULES = os.path.join(STATE, \"traffic-rules\")\nRESPONSES = os.path.join(STATE, \"traffic-responses\")\nASK_POLL_SECONDS = 0.2\nTCP_SCHEME = \"tcp://\"\n\n\ndef _load(path):\n    try:\n        with open(path) as f:\n            return json.load(f)\n    except (OSError, ValueError):\n        return None\n\n\ndef _rules(tcp):\n    try:\n        files = sorted(f for f in os.listdir(RULES) if f.endswith(\".json\"))\n    except OSError:\n        return []\n    rules = (_load(os.path.join(RULES, f)) for f in files)\n    return [r for r in rules if r and r.get(\"urlMask\", \"\").startswith(TCP_SCHEME) == tcp]\n\n\ndef _request_target(request):\n    \"\"\"host:port/path?query: the port always written out, the scheme left out.\"\"\"\n    return f\"{request.pretty_host.lower()}:{request.port}{request.path}\"\n\n\ndef _url_mask(mask):\n    \"\"\"The mask in _request_target's form: no scheme, and \"any\" for a port or path it leaves out.\"\"\"\n    if \"://\" in mask:\n        mask = mask.split(\"://\", 1)[1]\n    host, slash, path = mask.partition(\"/\")\n    if \":\" not in host:\n        host += \":*\"\n    return f\"{host.lower()}/{path if slash else '*'}\"\n\n\ndef _matching_url_rule(request):\n    target = _request_target(request)\n    for rule in _rules(tcp=False):\n        if fnmatch.fnmatchcase(target, _url_mask(rule[\"urlMask\"])):\n            return rule\n    return None\n\n\ndef _tcp_mask_matches(mask, ip, port):\n    address, _, mask_port = mask[len(TCP_SCHEME):].rpartition(\":\")\n    if mask_port != \"*\" and mask_port != str(port):\n        return False\n    if address == \"*\":\n        return True\n    try:\n        return ipaddress.ip_address(ip) in ipaddress.ip_network(address, strict=False)\n    except ValueError:\n        return False\n\n\ndef _matching_tcp_rule(ip, port):\n    for rule in _rules(tcp=True):\n        if _tcp_mask_matches(rule[\"urlMask\"], ip, port):\n            return rule\n    return None\n\n\nasync def _await_answer(name):\n    \"\"\"The ALLOW/DENY given for the rule after now, or None once the rule is no longer an ASK.\"\"\"\n    asked_at = time.time() * 1000\n    while True:\n        answer = _load(os.path.join(RESPONSES, f\"{name}.json\"))\n        if answer and answer.get(\"at\", 0) >= asked_at:\n            return answer.get(\"action\")\n        rule = _load(os.path.join(RULES, f\"{name}.json\"))\n        if not rule or rule.get(\"action\") != \"ASK\":\n            return None\n        # Never time.sleep: this runs on mitmproxy's event loop, shared by every connection.\n        await asyncio.sleep(ASK_POLL_SECONDS)\n\n\nasync def _verdict(rule):\n    \"\"\"Applies the rule's hold, if any; returns the refusal message, or None to carry on.\"\"\"\n    action = rule.get(\"action\")\n    if action == \"BLOCK\":\n        return f\"blocked by gateway rule {rule['name']}\"\n    if action == \"DELAY\":\n        await asyncio.sleep(max(0, rule.get(\"delayMs\", 0)) / 1000)\n    elif action == \"ASK\" and await _await_answer(rule[\"name\"]) == \"DENY\":\n        return f\"denied by gateway rule {rule['name']}\"\n    return None\n\n\nasync def request(flow: http.HTTPFlow):\n    rule = _matching_url_rule(flow.request)\n    refusal = rule and await _verdict(rule)\n    if refusal:\n        flow.response = http.Response.make(403, f\"{refusal}\\n\", {\"content-type\": \"text/plain\"})\n\n\nasync def server_connect(data: server_hooks.ServerConnectionHookData):\n    if not data.server.address:\n        return\n    rule = _matching_tcp_rule(data.server.address[0], data.server.address[1])\n    refusal = rule and await _verdict(rule)\n    if refusal:\n        data.server.error = refusal\n\n",
     "upstreams.py": "# mitmproxy addon applying the gateway's upstreams (see portal-gateway/upstream.ts) to traffic from\n# portals. Definitions are the JSON files the gateway service writes to /state/upstreams; this addon\n# keeps each upstream's OAuth credential in /state/credentials/<upstream>.oauth.json and reads its\n# API keys from /state/credentials/<upstream>.api-keys.json. Everything is re-read per request, so a\n# change takes effect without a reload.\n#\n# Clients sign in from dimensions, through the proxy:\n#   token endpoint   without a usable credential, requests go through and the response is kept as\n#                    the credential, reaching the dimension with fakes in place of the tokens. With\n#                    one, the gateway answers from it: a sign-in (whatever code it carries) and a\n#                    refresh made with a fake refresh token. A client's refresh goes upstream: the\n#                    gateway replays it (encoding, fields, User-Agent) with the real refresh token,\n#                    one at a time, and refreshes arriving together share its result. Every client\n#                    holds the same fakes, so they all get the new tokens. A sign-in is answered from\n#                    the credential, refreshed first if expired by replaying the last client refresh.\n#                    An expired credential it can't refresh (no client refresh to replay yet, or\n#                    upstream refused) counts as none: a sign-in goes to the upstream again.\n#   answers          other sign-in steps (a device flow's poll) answered as the definition says, once\n#                    there is a credential\n#   other requests   a fake in the mode's `present` location is replaced by the real secret\n\nimport asyncio\nimport http.client as http_client\nimport json\nimport os\nimport secrets\nimport string\nimport time\nimport urllib.parse\n\nfrom mitmproxy import http\n\nSTATE = \"/state\"\nUPSTREAMS = os.path.join(STATE, \"upstreams\")\nCREDENTIALS = os.path.join(STATE, \"credentials\")\n# A token this close to expiry counts as expired.\nREFRESH_MARGIN_MS = 60_000\n# Refreshes arriving within this long of the last one get its tokens instead of going upstream again.\nREFRESH_SHARED_MS = 5_000\nFAKE_ALPHABET = string.ascii_letters + string.digits + \"-_\"\nTOKEN_FIELDS = ((\"access\", \"access_token\"), (\"refresh\", \"refresh_token\"), (\"id\", \"id_token\"))\n\n# One refresh per upstream at a time: concurrent ones would each spend the rotating refresh token.\n_refresh_locks: dict[str, asyncio.Lock] = {}\n\n\ndef _now_ms():\n    return int(time.time() * 1000)\n\n\ndef _load(path):\n    try:\n        with open(path) as f:\n            return json.load(f)\n    except (OSError, ValueError):\n        return None\n\n\ndef _save(path, data):\n    tmp = f\"{path}.{secrets.token_hex(4)}.tmp\"\n    with open(tmp, \"w\") as f:\n        json.dump(data, f, indent=2)\n    os.replace(tmp, path)\n\n\ndef _definitions():\n    try:\n        files = sorted(f for f in os.listdir(UPSTREAMS) if f.endswith(\".json\"))\n    except OSError:\n        return []\n    definitions = (_load(os.path.join(UPSTREAMS, f)) for f in files)\n    return [d for d in definitions if d and d.get(\"name\")]\n\n\ndef _oauth_path(name):\n    return os.path.join(CREDENTIALS, f\"{name}.oauth.json\")\n\n\ndef _keys_path(name):\n    return os.path.join(CREDENTIALS, f\"{name}.api-keys.json\")\n\n\ndef _base(url):\n    return url.split(\"?\", 1)[0].split(\"#\", 1)[0]\n\n\ndef _hosts(mode):\n    return {h.lower() for h in mode.get(\"hosts\", [])}\n\n\n# --- fakes -----------------------------------------------------------------------------------------\n\n\ndef _random(length):\n    return \"\".join(secrets.choice(FAKE_ALPHABET) for _ in range(length))\n\n\ndef _issue_fake(shape, real):\n    if shape.get(\"jwt\"):\n        signature = real.rsplit(\".\", 1)[-1] if real.count(\".\") == 2 else \"\"\n        return {\"jwtSignature\": _random(max(len(signature), 43))}\n    prefix = shape.get(\"prefix\", \"\")\n    return {\"value\": prefix + _random(max(len(real) - len(prefix), 16))}\n\n\ndef _fake_value(stored, real):\n    if \"jwtSignature\" in stored:\n        header_and_claims = real.rsplit(\".\", 1)[0] if real.count(\".\") == 2 else real\n        return f\"{header_and_claims}.{stored['jwtSignature']}\"\n    return stored[\"value\"]\n\n\ndef _is_fake(stored, candidate):\n    if not stored or not candidate:\n        return False\n    if \"jwtSignature\" in stored:\n        return candidate.count(\".\") == 2 and candidate.rsplit(\".\", 1)[1] == stored[\"jwtSignature\"]\n    return candidate == stored[\"value\"]\n\n\n# --- presenting secrets ----------------------------------------------------------------------------\n\n\ndef _presented(request, present):\n    if \"query\" in present:\n        return request.query.get(present[\"query\"])\n    value = request.headers.get(present[\"header\"])\n    scheme = present.get(\"scheme\")\n    if value and scheme:\n        prefix = f\"{scheme} \"\n        return value[len(prefix):] if value.lower().startswith(prefix.lower()) else None\n    return value\n\n\ndef _present(request, present, secret):\n    if \"query\" in present:\n        request.query[present[\"query\"]] = secret\n    elif present.get(\"scheme\"):\n        request.headers[present[\"header\"]] = f\"{present['scheme']} {secret}\"\n    else:\n        request.headers[present[\"header\"]] = secret\n\n\ndef _force(request, force):\n    if not force:\n        return\n    if force.get(\"target\"):\n        target = urllib.parse.urlsplit(force[\"target\"])\n        request.scheme = target.scheme or request.scheme\n        request.host = target.hostname or request.host\n        request.port = target.port or (443 if request.scheme == \"https\" else 80)\n    if force.get(\"path\"):\n        request.path = force[\"path\"].rstrip(\"/\") + request.path\n    for key, value in force.get(\"query\", {}).items():\n        request.query[key] = value\n    for key, value in force.get(\"headers\", {}).items():\n        request.headers[key] = value\n\n\ndef _swap_oauth(request, name, mode):\n    credential = _load(_oauth_path(name))\n    presented = _presented(request, mode[\"present\"])\n    if credential and _is_fake(credential[\"fakes\"].get(\"access\"), presented):\n        _present(request, mode[\"present\"], credential[\"access\"])\n        return True\n    return False\n\n\ndef _swap_api_key(request, name, mode):\n    stored = _load(_keys_path(name)) or {}\n    presented = _presented(request, mode[\"present\"])\n    for key in stored.get(\"keys\", {}).values():\n        if presented and presented == key[\"fake\"]:\n            _present(request, mode[\"present\"], key[\"key\"])\n            return True\n    return False\n\n\n# --- the token endpoint ----------------------------------------------------------------------------\n\n\ndef _parse_form_or_json(text, content_type):\n    if not text:\n        return {}\n    if \"json\" in (content_type or \"\"):\n        try:\n            value = json.loads(text)\n            return value if isinstance(value, dict) else {}\n        except ValueError:\n            return {}\n    return dict(urllib.parse.parse_qsl(text))\n\n\ndef _refresh_request(flow, fields):\n    \"\"\"How a client refreshes, to replay with the real refresh token: everything but that token.\"\"\"\n    return {\n        \"contentType\": flow.request.headers.get(\"content-type\", \"\"),\n        \"userAgent\": flow.request.headers.get(\"user-agent\"),\n        \"fields\": {k: v for k, v in fields.items() if k != \"refresh_token\"},\n    }\n\n\ndef _store_tokens(name, mode, body, refresh_request):\n    \"\"\"Keeps a token response as the upstream's credential and returns it.\"\"\"\n    path = _oauth_path(name)\n    credential = dict(_load(path) or {})\n    if refresh_request:\n        credential[\"refreshRequest\"] = refresh_request\n    now = _now_ms()\n    for key, field in TOKEN_FIELDS:\n        if body.get(field):\n            credential[key] = body[field]\n    if \"expires_in\" in body:\n        credential[\"expiresAt\"] = now + int(body[\"expires_in\"]) * 1000\n    if \"refresh_token_expires_in\" in body:\n        credential[\"refreshExpiresAt\"] = now + int(body[\"refresh_token_expires_in\"]) * 1000\n    if body.get(\"scope\"):\n        credential[\"scopes\"] = body[\"scope\"].split()\n    credential[\"lastRefresh\"] = now\n    fakes = dict(credential.get(\"fakes\") or {})\n    for key, _ in TOKEN_FIELDS:\n        shape = mode[\"fakes\"].get(key)\n        if shape and credential.get(key) and key not in fakes:\n            fakes[key] = _issue_fake(shape, credential[key])\n    credential[\"fakes\"] = fakes\n    stripped = set((mode.get(\"strip\") or {}).get(\"fields\", []))\n    credential[\"response\"] = {k: v for k, v in body.items() if k not in stripped}\n    _save(path, credential)\n    return credential\n\n\ndef _client_body(mode, credential):\n    \"\"\"The token response the dimension gets: the last real one, with fakes for every token.\"\"\"\n    body = dict(credential.get(\"response\") or {})\n    fakes = credential[\"fakes\"]\n    for key, field in TOKEN_FIELDS:\n        if field not in body:\n            continue\n        if key in fakes and credential.get(key):\n            body[field] = _fake_value(fakes[key], credential[key])\n        else:\n            del body[field]  # a token with no fake shape never reaches a dimension\n    now = _now_ms()\n    if credential.get(\"expiresAt\") and \"expires_in\" in body:\n        body[\"expires_in\"] = max(0, (credential[\"expiresAt\"] - now) // 1000)\n    if credential.get(\"refreshExpiresAt\") and \"refresh_token_expires_in\" in body:\n        body[\"refresh_token_expires_in\"] = max(0, (credential[\"refreshExpiresAt\"] - now) // 1000)\n    return body\n\n\ndef _refresh_upstream(mode, credential):\n    \"\"\"Replays the client's refresh request with the real refresh token; returns (status, parsed body\n    or raw bytes). http.client, unlike urllib, adds no User-Agent of its own: a client that sent none\n    stays that way.\"\"\"\n    template = credential[\"refreshRequest\"]\n    fields = dict(template[\"fields\"], refresh_token=credential[\"refresh\"])\n    content_type = template[\"contentType\"] or \"application/x-www-form-urlencoded\"\n    data = json.dumps(fields) if \"json\" in content_type else urllib.parse.urlencode(fields)\n    headers = {\"content-type\": content_type, \"accept\": \"application/json\"}\n    if template.get(\"userAgent\"):\n        headers[\"user-agent\"] = template[\"userAgent\"]\n    url = urllib.parse.urlsplit(mode[\"tokenUrl\"])\n    connection_type = http_client.HTTPSConnection if url.scheme == \"https\" else http_client.HTTPConnection\n    connection = connection_type(url.hostname, url.port, timeout=30)\n    try:\n        connection.request(\"POST\", url.path + (f\"?{url.query}\" if url.query else \"\"), body=data.encode(), headers=headers)\n        response = connection.getresponse()\n        raw = response.read()\n        try:\n            return response.status, json.loads(raw)\n        except ValueError:\n            return response.status, raw\n    finally:\n        connection.close()\n\n\nasync def _answer_from_credential(flow, name, mode, refresh_request):\n    \"\"\"Answers a sign-in, or a refresh made with a fake (`refresh_request`), with the credential's\n    fakes. A refresh is replayed upstream first unless another one just was; a sign-in only if the\n    credential has expired. Returns False, answering nothing, when a sign-in can't be given valid\n    tokens: expired, and no client refresh to replay yet or upstream refused it. A client's refresh\n    gets upstream's refusal instead.\"\"\"\n    lock = _refresh_locks.setdefault(name, asyncio.Lock())\n    async with lock:\n        credential = _load(_oauth_path(name))\n        if refresh_request and credential.get(\"refreshRequest\") != refresh_request:\n            credential[\"refreshRequest\"] = refresh_request\n            _save(_oauth_path(name), credential)\n        now = _now_ms()\n        expired = not credential.get(\"expiresAt\") or credential[\"expiresAt\"] - now < REFRESH_MARGIN_MS\n        just_refreshed = now - credential.get(\"lastRefresh\", 0) < REFRESH_SHARED_MS\n        if expired or (refresh_request and not just_refreshed):\n            if not (credential.get(\"refresh\") and credential.get(\"refreshRequest\")):\n                if not refresh_request:\n                    return False\n                # A client's refresh with nothing to refresh with: all there is to give it.\n                flow.response = http.Response.make(\n                    200, json.dumps(_client_body(mode, credential)), {\"content-type\": \"application/json\"}\n                )\n                return True\n            status, body = await asyncio.to_thread(_refresh_upstream, mode, credential)\n            if status != 200 or not isinstance(body, dict) or \"access_token\" not in body:\n                if not refresh_request:\n                    return False\n                content = body if isinstance(body, bytes) else json.dumps(body).encode()\n                flow.response = http.Response.make(status, content, {\"content-type\": \"application/json\"})\n                return True\n            credential = _store_tokens(name, mode, body, None)\n    flow.response = http.Response.make(\n        200, json.dumps(_client_body(mode, credential)), {\"content-type\": \"application/json\"}\n    )\n    return True\n\n\nasync def request(flow: http.HTTPFlow):\n    if flow.response:  # already answered, e.g. by a traffic rule\n        return\n    host = flow.request.pretty_host.lower()\n    url = _base(flow.request.pretty_url)\n    for definition in _definitions():\n        name = definition[\"name\"]\n        oauth = definition.get(\"modes\", {}).get(\"oauth\")\n        api_key = definition.get(\"modes\", {}).get(\"apiKey\")\n        forced = definition.get(\"modes\", {}).get(\"forced\")\n        credential = _load(_oauth_path(name)) if oauth else None\n        if oauth and url == _base(oauth[\"tokenUrl\"]):\n            fields = _parse_form_or_json(flow.request.get_text(strict=False), flow.request.headers.get(\"content-type\"))\n            refreshing = fields.get(\"grant_type\") == \"refresh_token\"\n            refresh_request = _refresh_request(flow, fields) if refreshing else None\n            # A refresh token the gateway didn't issue is a client that signed in before the upstream\n            # was registered (or elsewhere): let it through, and keep what it gets.\n            foreign_refresh = refreshing and not _is_fake(\n                (credential or {}).get(\"fakes\", {}).get(\"refresh\"), fields.get(\"refresh_token\")\n            )\n            if credential and not foreign_refresh and await _answer_from_credential(flow, name, oauth, refresh_request):\n                return\n            flow.metadata[\"hyperbrane_token\"] = (name, refresh_request)\n            return\n        if credential:\n            for answer in oauth.get(\"answers\", []):\n                if url == _base(answer[\"url\"]):\n                    flow.response = http.Response.make(\n                        answer.get(\"status\", 200), json.dumps(answer[\"json\"]), {\"content-type\": \"application/json\"}\n                    )\n                    return\n        for mode, swap in ((oauth, _swap_oauth), (api_key, _swap_api_key), (forced, None)):\n            if mode and host in _hosts(mode):\n                if swap:\n                    swap(flow.request, name, mode)\n                _force(flow.request, mode.get(\"force\"))\n\n\ndef responseheaders(flow: http.HTTPFlow):\n    # Only token responses are rewritten; everything else streams through as it arrives. mitmproxy\n    # otherwise holds each response until its body is complete, so a model's streamed reply (SSE)\n    # reached the dimension in one piece at the end of the turn.\n    if not flow.metadata.get(\"hyperbrane_token\"):\n        flow.response.stream = True\n\n\ndef response(flow: http.HTTPFlow):\n    token = flow.metadata.get(\"hyperbrane_token\")\n    if not token:\n        return\n    name, refresh_request = token\n    definition = next((d for d in _definitions() if d[\"name\"] == name), None)\n    oauth = (definition or {}).get(\"modes\", {}).get(\"oauth\")\n    if not oauth:\n        return\n    body = _parse_form_or_json(flow.response.get_text(strict=False), \"json\")\n    if flow.response.status_code == 200 and body.get(\"access_token\"):\n        credential = _store_tokens(name, oauth, body, refresh_request)\n        flow.response.text = json.dumps(_client_body(oauth, credential))\n    for header in (oauth.get(\"strip\") or {}).get(\"headers\", []):\n        flow.response.headers.pop(header, None)\n",
 };

package/dist/portal-gateway/portalClient.d.ts

@@ -0,0 +1,5 @@
+import type { Sandbox } from "../sandbox/api.ts";
+import type { PortalClient } from "./api.ts";
+export declare function createPortalClient(sandbox: Sandbox, options?: {
+    dataDirectory?: string;
+}): PortalClient;

package/dist/portal-gateway/portalClient.js

@@ -0,0 +1,4 @@
+import { createPortalService } from "./portalService.js";
+export function createPortalClient(sandbox, options = {}) {
+    return createPortalService(sandbox, options);
+}