hyperbrane 0.1.0

package/dist/portal-gateway/api.js

@@ -0,0 +1,12 @@
+/** The request can't be satisfied as sent (bad name, unsupported action, ...). */
+export class GatewayInvalidError extends Error {
+    name = "GatewayInvalidError";
+}
+/** The name is taken with a different spec, or by a container hyperbrane doesn't own. */
+export class GatewayConflictError extends Error {
+    name = "GatewayConflictError";
+}
+/** A gateway, rule, dimension or portal the request refers to doesn't exist. */
+export class GatewayNotFoundError extends Error {
+    name = "GatewayNotFoundError";
+}

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

@@ -0,0 +1,3 @@
+import type { FakeShape } from "./upstream.ts";
+/** A fake for an API key: the shape's prefix, then random characters as long as the real key. */
+export declare function issueKeyFake(shape: FakeShape, key: string): string;

package/dist/portal-gateway/fakes.js

@@ -0,0 +1,11 @@
+// Like the gateway addon (image/upstreams.py), which issues the fakes for captured tokens.
+const ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
+function random(length) {
+    const bytes = crypto.getRandomValues(new Uint8Array(length));
+    return Array.from(bytes, (byte) => ALPHABET[byte % ALPHABET.length]).join("");
+}
+/** A fake for an API key: the shape's prefix, then random characters as long as the real key. */
+export function issueKeyFake(shape, key) {
+    const prefix = "prefix" in shape ? shape.prefix : "";
+    return prefix + random(Math.max(key.length - prefix.length, 16));
+}

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

@@ -0,0 +1,37 @@
+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";
+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>;
+}
+/** 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): GatewayService;

package/dist/portal-gateway/gatewayService.js

@@ -0,0 +1,380 @@
+import { isIPv4 } from "node:net";
+import { DockerError } from "../lib/docker.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 { 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 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 function assertValidName(kind, name) {
+    try {
+        checkName(name);
+    }
+    catch (error) {
+        if (error instanceof InvalidNameError)
+            throw new GatewayInvalidError(`invalid ${kind} name: ${error.message}`);
+        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) {
+    // 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.
+    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" });
+        return { name: gateway.name };
+    }
+    // A container from an older image is replaced: everything worth keeping (CA, credentials, rules)
+    // is in the mounted state directory. Its portals are re-wired by the portal watcher, or by the
+    // restore every command runs first.
+    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 is listening (so the redirect rules are in) 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", "-Hltn", `sport = :${PROXY_PORT}`], user: "root" });
+            return result.exitCode === 0 && result.stdout.trim() !== "";
+        }
+        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);
+    }
+    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));
+    }
+    async function listGateways() {
+        return (await storage.listGateways()).map(({ name }) => ({ name }));
+    }
+    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;
+    }
+    // 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);
+        }
+        else if (keyAt > 0) {
+            await deleteApiKey(gatewayName, credentialName.slice(0, keyAt), credentialName.slice(keyAt + ".key.".length));
+        }
+        else {
+            throw new GatewayInvalidError(`credential names are <upstream>.oauth or <upstream>.key.<key>, not ${credentialName}`);
+        }
+    }
+    async function registerUpstream(gatewayName, upstream) {
+        await requireGateway(gatewayName);
+        const definition = validUpstream(upstream);
+        await storage.saveUpstream(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));
+    }
+    async function removeUpstream(gatewayName, upstreamName) {
+        assertValidName("gateway", gatewayName);
+        assertValidName("upstream", upstreamName);
+        await storage.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("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 };
+    }
+    async function deleteApiKey(gatewayName, upstreamName, keyName) {
+        await requireUpstream(gatewayName, 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 });
+    }
+    async function createTrafficRule(gatewayName, rule) {
+        await requireGateway(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`);
+        }
+        return requested;
+    }
+    async function updateTrafficRule(gatewayName, rule) {
+        await requireGateway(gatewayName);
+        const requested = validTrafficRule(rule);
+        await requireTrafficRule(gatewayName, rule.name);
+        await storage.saveTrafficRule(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);
+    }
+    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));
+    }
+    // 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;
+    }
+    return {
+        createGateway,
+        destroyGateway,
+        listGateways,
+        restartGateway,
+        listCredentials,
+        deleteCredential,
+        registerUpstream,
+        listUpstreams,
+        removeUpstream,
+        setApiKey,
+        deleteApiKey,
+        createTrafficRule,
+        updateTrafficRule,
+        deleteTrafficRule,
+        listTrafficRules,
+        trafficRuleRespond,
+    };
+}
+/** 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 } = upstream.modes ?? {};
+    if (!oauth && !apiKey)
+        throw new GatewayInvalidError(`upstream ${upstream.name} needs an oauth or apiKey mode`);
+    for (const mode of [oauth, apiKey]) {
+        if (mode && (!Array.isArray(mode.hosts) || mode.hosts.length === 0 || !mode.present)) {
+            throw new GatewayInvalidError(`upstream ${upstream.name}: every mode needs hosts and present`);
+        }
+    }
+    if (oauth && (!oauth.tokenUrl || !oauth.fakes?.access)) {
+        throw new GatewayInvalidError(`upstream ${upstream.name}: oauth needs tokenUrl and fakes.access`);
+    }
+    if (apiKey && !apiKey.fake)
+        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 === "") {
+        throw new GatewayInvalidError(`traffic rule ${rule.name} needs a urlMask`);
+    }
+    if (rule.urlMask.startsWith(TCP_SCHEME))
+        assertValidTcpMask(rule.name, rule.urlMask);
+    if (rule.action === "INTERCEPT")
+        throw new GatewayInvalidError("INTERCEPT traffic rules are not supported yet");
+    if (rule.action !== "BLOCK" && rule.action !== "DELAY" && rule.action !== "ASK") {
+        throw new GatewayInvalidError(`invalid traffic rule action: ${rule.action}`);
+    }
+    if (!Number.isFinite(rule.delayMs) || rule.delayMs < 0) {
+        throw new GatewayInvalidError(`traffic rule ${rule.name} needs a delayMs of 0 or more`);
+    }
+    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(":");
+    const address = target.slice(0, separator);
+    const port = target.slice(separator + 1);
+    const [ip, prefix, ...rest] = address.split("/");
+    const validAddress = address === "*" ||
+        (isIPv4(ip) && rest.length === 0 && (prefix === undefined || (/^\d+$/.test(prefix) && Number(prefix) <= 32)));
+    const validPort = port === "*" || (/^\d+$/.test(port) && Number(port) >= 1 && Number(port) <= 65535);
+    if (separator < 0 || !validAddress || !validPort) {
+        throw new GatewayInvalidError(`traffic rule ${ruleName}: a tcp:// urlMask is tcp://<IPv4 address, CIDR or *>:<port or *>, not ${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/gatewayStorage.d.ts

@@ -0,0 +1,66 @@
+import type { Sandbox } from "../sandbox/api.ts";
+import type { Gateway, TrafficRule } from "./api.ts";
+import type { ApiKeyCredential, OAuthCredential, UpstreamDefinition } from "./upstream.ts";
+/** "creating" until the container has come up once; a create that crashed stays "creating" until retried. */
+export type GatewayRecord = Gateway & {
+    state: "creating" | "ready";
+};
+export type TrafficRuleResponse = {
+    name: string;
+    action: "ALLOW" | "DENY";
+    at: number;
+};
+/** Every name must pass checkName; operations throw InvalidNameError otherwise. */
+export interface GatewayStorage {
+    /** Stores the record unless one with that name exists; returns whichever record is stored afterwards. */
+    insertGateway(gateway: GatewayRecord): Promise<GatewayRecord>;
+    /** Replaces the record. */
+    saveGateway(gateway: GatewayRecord): Promise<void>;
+    /** Null if missing. */
+    readGateway(gatewayName: string): Promise<GatewayRecord | null>;
+    /** Removes the gateway's state (credentials, rules, CA), then its record. No-op if missing. */
+    removeGateway(gatewayName: string): Promise<void>;
+    listGateways(): Promise<GatewayRecord[]>;
+    /**
+     * Sandbox path of the directory mounted into the gateway container as /state. Creates it with
+     * its upstreams/, credentials/, traffic-rules/, traffic-responses/ and mitmproxy/ subdirectories.
+     */
+    ensureStateDirectory(gatewayName: string): Promise<string>;
+    /** Replaces the definition. */
+    saveUpstream(gatewayName: string, upstream: UpstreamDefinition): Promise<void>;
+    /** Null if missing. */
+    readUpstream(gatewayName: string, upstreamName: string): Promise<UpstreamDefinition | null>;
+    /** Removes the definition and its credentials. No-op if missing. */
+    removeUpstream(gatewayName: string, upstreamName: string): Promise<void>;
+    listUpstreams(gatewayName: string): Promise<UpstreamDefinition[]>;
+    /** Written by the gateway as it captures tokens; null until a client signs in. */
+    readOAuthCredential(gatewayName: string, upstreamName: string): Promise<OAuthCredential | null>;
+    /** No-op if missing. */
+    removeOAuthCredential(gatewayName: string, upstreamName: string): Promise<void>;
+    /** Null if none were ever set. */
+    readApiKeys(gatewayName: string, upstreamName: string): Promise<ApiKeyCredential | null>;
+    /** Every credential the gateway holds, by name ("<upstream>.oauth", "<upstream>.api-keys"), at once. */
+    listCredentials(gatewayName: string): Promise<Map<string, unknown>>;
+    /** Replaces the upstream's keys. */
+    saveApiKeys(gatewayName: string, upstreamName: string, keys: ApiKeyCredential): Promise<void>;
+    /** No-op if missing. */
+    removeApiKeys(gatewayName: string, upstreamName: string): Promise<void>;
+    /** Stores the record unless one with that name exists; returns whichever record is stored afterwards. */
+    insertTrafficRule(gatewayName: string, rule: TrafficRule): Promise<TrafficRule>;
+    /** Replaces the record. */
+    saveTrafficRule(gatewayName: string, rule: TrafficRule): Promise<void>;
+    /** Null if missing. */
+    readTrafficRule(gatewayName: string, ruleName: string): Promise<TrafficRule | null>;
+    /** Removes the rule and its last response. No-op if missing. */
+    removeTrafficRule(gatewayName: string, ruleName: string): Promise<void>;
+    listTrafficRules(gatewayName: string): Promise<TrafficRule[]>;
+    /** Replaces the rule's last response. */
+    saveTrafficRuleResponse(gatewayName: string, response: TrafficRuleResponse): Promise<void>;
+}
+/**
+ * `dir` is a sandbox path; defaults to ~/.local/share/hyperbrane of the sandbox's user. Layout:
+ * gateways/<gateway>.json, and gateway-state/<gateway>/ holding everything the container sees:
+ * upstreams/<upstream>.json, credentials/<upstream>.oauth.json and <upstream>.api-keys.json,
+ * traffic-rules/<rule>.json, traffic-responses/<rule>.json, mitmproxy/.
+ */
+export declare function createGatewayStorage(sandbox: Sandbox, dir?: string): GatewayStorage;

package/dist/portal-gateway/gatewayStorage.js

@@ -0,0 +1,125 @@
+import { checkName, createJsonDirectory, defaultDataDir } from "../lib/jsonDirectory.js";
+/**
+ * `dir` is a sandbox path; defaults to ~/.local/share/hyperbrane of the sandbox's user. Layout:
+ * gateways/<gateway>.json, and gateway-state/<gateway>/ holding everything the container sees:
+ * upstreams/<upstream>.json, credentials/<upstream>.oauth.json and <upstream>.api-keys.json,
+ * traffic-rules/<rule>.json, traffic-responses/<rule>.json, mitmproxy/.
+ */
+export function createGatewayStorage(sandbox, dir) {
+    async function dataDir() {
+        return dir ?? defaultDataDir(sandbox);
+    }
+    async function stateDir(gatewayName) {
+        return `${await dataDir()}/gateway-state/${checkName(gatewayName)}`;
+    }
+    const gateways = createJsonDirectory(sandbox, async () => `${await dataDir()}/gateways`);
+    function stateSubdirectory(gatewayName, subdirectory) {
+        checkName(gatewayName);
+        return createJsonDirectory(sandbox, async () => `${await stateDir(gatewayName)}/${subdirectory}`);
+    }
+    const upstreams = (gatewayName) => stateSubdirectory(gatewayName, "upstreams");
+    const credentials = (gatewayName) => stateSubdirectory(gatewayName, "credentials");
+    const trafficRules = (gatewayName) => stateSubdirectory(gatewayName, "traffic-rules");
+    const trafficResponses = (gatewayName) => stateSubdirectory(gatewayName, "traffic-responses");
+    async function insertGateway(gateway) {
+        return gateways.insert(gateway.name, gateway);
+    }
+    async function saveGateway(gateway) {
+        await gateways.save(gateway.name, gateway);
+    }
+    async function readGateway(gatewayName) {
+        return gateways.read(gatewayName);
+    }
+    async function removeGateway(gatewayName) {
+        await sandbox.removeDirectory(await stateDir(gatewayName));
+        await gateways.remove(gatewayName);
+    }
+    async function listGateways() {
+        return gateways.list();
+    }
+    async function ensureStateDirectory(gatewayName) {
+        const path = await stateDir(gatewayName);
+        for (const subdirectory of ["upstreams", "credentials", "traffic-rules", "traffic-responses", "mitmproxy"]) {
+            await sandbox.createDirectory(`${path}/${subdirectory}`);
+        }
+        return path;
+    }
+    async function saveUpstream(gatewayName, upstream) {
+        await upstreams(gatewayName).save(upstream.name, upstream);
+    }
+    async function readUpstream(gatewayName, upstreamName) {
+        return upstreams(gatewayName).read(upstreamName);
+    }
+    // Definition last: while any credential is left, the upstream is still there to retry the removal.
+    async function removeUpstream(gatewayName, upstreamName) {
+        await removeOAuthCredential(gatewayName, upstreamName);
+        await removeApiKeys(gatewayName, upstreamName);
+        await upstreams(gatewayName).remove(upstreamName);
+    }
+    async function listUpstreams(gatewayName) {
+        return upstreams(gatewayName).list();
+    }
+    // Credential names are "<upstream>.oauth" and "<upstream>.api-keys", checked as names like any other.
+    async function readOAuthCredential(gatewayName, upstreamName) {
+        return (await credentials(gatewayName).read(`${checkName(upstreamName)}.oauth`));
+    }
+    async function removeOAuthCredential(gatewayName, upstreamName) {
+        await credentials(gatewayName).remove(`${checkName(upstreamName)}.oauth`);
+    }
+    /** Every credential the gateway holds, by name ("<upstream>.oauth", "<upstream>.api-keys"), at once. */
+    async function listCredentials(gatewayName) {
+        return new Map(await credentials(gatewayName).entries());
+    }
+    async function readApiKeys(gatewayName, upstreamName) {
+        return (await credentials(gatewayName).read(`${checkName(upstreamName)}.api-keys`));
+    }
+    async function saveApiKeys(gatewayName, upstreamName, keys) {
+        await credentials(gatewayName).save(`${checkName(upstreamName)}.api-keys`, keys);
+    }
+    async function removeApiKeys(gatewayName, upstreamName) {
+        await credentials(gatewayName).remove(`${checkName(upstreamName)}.api-keys`);
+    }
+    async function insertTrafficRule(gatewayName, rule) {
+        return trafficRules(gatewayName).insert(rule.name, rule);
+    }
+    async function saveTrafficRule(gatewayName, rule) {
+        await trafficRules(gatewayName).save(rule.name, rule);
+    }
+    async function readTrafficRule(gatewayName, ruleName) {
+        return trafficRules(gatewayName).read(ruleName);
+    }
+    async function removeTrafficRule(gatewayName, ruleName) {
+        await trafficRules(gatewayName).remove(ruleName);
+        await trafficResponses(gatewayName).remove(ruleName);
+    }
+    async function listTrafficRules(gatewayName) {
+        return trafficRules(gatewayName).list();
+    }
+    async function saveTrafficRuleResponse(gatewayName, response) {
+        await trafficResponses(gatewayName).save(response.name, response);
+    }
+    return {
+        insertGateway,
+        saveGateway,
+        readGateway,
+        removeGateway,
+        listGateways,
+        ensureStateDirectory,
+        saveUpstream,
+        readUpstream,
+        removeUpstream,
+        listUpstreams,
+        readOAuthCredential,
+        removeOAuthCredential,
+        readApiKeys,
+        listCredentials,
+        saveApiKeys,
+        removeApiKeys,
+        insertTrafficRule,
+        saveTrafficRule,
+        readTrafficRule,
+        removeTrafficRule,
+        listTrafficRules,
+        saveTrafficRuleResponse,
+    };
+}

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

@@ -0,0 +1,6 @@
+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 = "v16";
+export declare const GATEWAY_IMAGE_REPOSITORY = "hyperbrane-gateway";
+export declare function createGatewayImage(docker: DockerClient): ManagedImage;

package/dist/portal-gateway/image.js

@@ -0,0 +1,13 @@
+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 = "v16";
+export const GATEWAY_IMAGE_REPOSITORY = "hyperbrane-gateway";
+export function createGatewayImage(docker) {
+    return createManagedImage(docker, {
+        repository: GATEWAY_IMAGE_REPOSITORY,
+        version: GATEWAY_IMAGE_VERSION,
+        context: IMAGE_FILES,
+    });
+}

package/dist/portal-gateway/imageFiles.generated.d.ts

@@ -0,0 +1 @@
+export declare const IMAGE_FILES: Record<string, string>;