hyperbrane 0.1.1 → 0.2.0

package/dist/portal-gateway/control.js

@@ -0,0 +1,657 @@
+import { dimensionLayout } from "../dimension/api.js";
+import { exitEnv, records, runControl } from "../lib/control.js";
+import { sh } from "../lib/sh.js";
+import { HYPERBRANE_VERSION } from "../lib/version.js";
+import { GatewayConflictError, GatewayInvalidError, GatewayNotFoundError } from "./api.js";
+import { GATEWAY_IMAGE_REPOSITORY, GATEWAY_IMAGE_VERSION } from "./image.js";
+import { transportBundle } from "./transportBundle.js";
+export const GATEWAY_STATE_PATH = "/state";
+const GATEWAY_IMAGE = `${GATEWAY_IMAGE_REPOSITORY}:${GATEWAY_IMAGE_VERSION}`;
+const PROXY_PORT = 8080;
+const DNS_PORT = 5353;
+const READY_TIMEOUT_S = 60;
+const SUBNET_COUNT = 1 << 14;
+const TRANSPORT_BUN_VERSION = "1.4.3";
+const EXIT = { invalid: 40, conflict: 41, notFound: 42, needImage: 43, needBundle: 44 };
+export function gatewayContainerName(gatewayName) {
+    return `hybgw-${gatewayName}`;
+}
+export function gatewayCaCertificatePath(stateDirectory) {
+    return `${stateDirectory}/mitmproxy/mitmproxy-ca-cert.pem`;
+}
+async function run(host, script, env, options) {
+    const result = await runControl(host, PORTAL_FUNCTIONS, script, { ...portalEnv(), ...env }, options);
+    if (result.exitCode === EXIT.needImage)
+        return false;
+    return { result };
+}
+export function portalEnv() {
+    return {
+        DIMENSION_PREFIX: dimensionLayout.containerName(""),
+        GATEWAY_PREFIX: gatewayContainerName(""),
+        GATEWAY_IMAGE,
+        CA_BUNDLE: dimensionLayout.caBundlePath(),
+        TRUST_SCRIPT: TRUST_GATEWAY_SCRIPT,
+        ...exitEnv(EXIT),
+    };
+}
+function check(ran, what) {
+    if (!ran)
+        throw new Error(`${what}: the gateway image is missing`);
+    const { result } = ran;
+    const said = result.stderr.trim();
+    switch (result.exitCode) {
+        case 0:
+            return result;
+        case EXIT.invalid:
+            throw new GatewayInvalidError(said);
+        case EXIT.conflict:
+            throw new GatewayConflictError(said);
+        case EXIT.notFound:
+            throw new GatewayNotFoundError(said);
+        default:
+            throw new Error(`${what} failed (exit ${result.exitCode}): ${said || result.stdout.trim()}`);
+    }
+}
+async function withImage(ensureImage, attempt, what) {
+    let ran = await attempt();
+    if (!ran) {
+        await ensureImage();
+        ran = await attempt();
+    }
+    return check(ran, what);
+}
+export function gatewayControl(host, ensureImage, options = {}) {
+    const gatewayEnv = (gatewayName) => ({ GATEWAY: gatewayName });
+    const call = (script, env, what) => withImage(ensureImage, () => run(host, script, env, options), what);
+    return {
+        async createGateway(gatewayName, upstreams) {
+            const lines = upstreams.map((upstream) => `${upstream.name}\t${JSON.stringify(upstream)}`).join("\n");
+            const env = { ...gatewayEnv(gatewayName), UPSTREAMS: lines, VERSION: HYPERBRANE_VERSION, STATE_PATH: GATEWAY_STATE_PATH, ...readyEnv() };
+            await call(CREATE_GATEWAY, env, `creating gateway ${gatewayName}`);
+        },
+        async destroyGateway(gatewayName) {
+            await call(DESTROY_GATEWAY, gatewayEnv(gatewayName), `destroying gateway ${gatewayName}`);
+        },
+        async restartGateway(gatewayName) {
+            await call(RESTART_GATEWAY, { ...gatewayEnv(gatewayName), ...readyEnv() }, `restarting gateway ${gatewayName}`);
+        },
+        async startTransport(gatewayName, endpoint, { restart, }) {
+            const { source, build } = await transportBundle();
+            const env = {
+                ...gatewayEnv(gatewayName),
+                PORT: String(endpoint.port),
+                SECRET: endpoint.secret,
+                BUILD: build,
+                BUN_VERSION: TRANSPORT_BUN_VERSION,
+                RESTART: restart ? "1" : "",
+            };
+            const what = `starting gateway ${gatewayName}'s transport worker`;
+            let ran = await run(host, START_TRANSPORT, env, options);
+            if (ran && ran.result.exitCode === EXIT.needBundle) {
+                await host.writeFile(`${ran.result.stdout.trim()}/transport-${build}.js`, source);
+                ran = await run(host, START_TRANSPORT, env, options);
+            }
+            check(ran, what);
+        },
+        async listGateways() {
+            const result = await call(PRINT_RECORDS, { DIRECTORY: "gateways" }, "listing gateways");
+            return records(result.stdout).map(([name]) => ({ name }));
+        },
+        async registerUpstream(gatewayName, upstream) {
+            const env = { ...gatewayEnv(gatewayName), FILE: `upstreams/${upstream.name}.json`, CONTENT: `${JSON.stringify(upstream, null, 2)}\n` };
+            await call(WRITE_STATE, env, `registering upstream ${upstream.name}`);
+        },
+        async listUpstreams(gatewayName) {
+            const result = await call(LIST_STATE, { ...gatewayEnv(gatewayName), DIRECTORY: "upstreams" }, `listing gateway ${gatewayName}'s upstreams`);
+            return records(result.stdout).map(([, upstream]) => upstream);
+        },
+        async removeUpstream(gatewayName, upstreamName) {
+            await call(REMOVE_UPSTREAM, { ...gatewayEnv(gatewayName), UPSTREAM: upstreamName }, `removing upstream ${upstreamName}`);
+        },
+        async listCredentials(gatewayName) {
+            const result = await call(LIST_CREDENTIALS, gatewayEnv(gatewayName), `listing gateway ${gatewayName}'s credentials`);
+            return records(result.stdout).map(([header, apiKeys]) => {
+                const [upstream = "", oauth] = header.split(" ");
+                return { upstream, oauth: oauth === "1", apiKeys };
+            });
+        },
+        async removeOAuthCredential(gatewayName, upstreamName) {
+            await call(REMOVE_STATE, { ...gatewayEnv(gatewayName), FILE: `credentials/${upstreamName}.oauth.json` }, `removing ${upstreamName}'s sign-in`);
+        },
+        async setApiKey(gatewayName, upstreamName, keyName, key, fakeCharacters) {
+            const env = { ...gatewayEnv(gatewayName), UPSTREAM: upstreamName, KEY_NAME: keyName, KEY: key, FAKE_CHARACTERS: fakeCharacters };
+            return (await call(SET_API_KEY, env, `setting API key ${keyName}`)).stdout.trim();
+        },
+        async deleteApiKey(gatewayName, upstreamName, keyName) {
+            await call(DELETE_API_KEY, { ...gatewayEnv(gatewayName), UPSTREAM: upstreamName, KEY_NAME: keyName }, `deleting API key ${keyName}`);
+        },
+        async createTrafficRule(gatewayName, rule) {
+            await call(CREATE_TRAFFIC_RULE, { ...gatewayEnv(gatewayName), RULE: rule.name, CONTENT: trafficRuleFile(rule) }, `creating traffic rule ${rule.name}`);
+        },
+        async updateTrafficRule(gatewayName, rule) {
+            await call(UPDATE_TRAFFIC_RULE, { ...gatewayEnv(gatewayName), RULE: rule.name, CONTENT: trafficRuleFile(rule) }, `updating traffic rule ${rule.name}`);
+        },
+        async deleteTrafficRule(gatewayName, ruleName) {
+            await call(DELETE_TRAFFIC_RULE, { ...gatewayEnv(gatewayName), RULE: ruleName }, `deleting traffic rule ${ruleName}`);
+        },
+        async listTrafficRules(gatewayName) {
+            const result = await call(LIST_STATE, { ...gatewayEnv(gatewayName), DIRECTORY: "traffic-rules" }, `listing gateway ${gatewayName}'s traffic rules`);
+            return records(result.stdout).map(([, rule]) => rule);
+        },
+        async trafficRuleRespond(gatewayName, ruleName, action) {
+            const response = `${JSON.stringify({ name: ruleName, action, at: Date.now() }, null, 2)}\n`;
+            await call(RESPOND_TRAFFIC_RULE, { ...gatewayEnv(gatewayName), RULE: ruleName, CONTENT: response }, `answering traffic rule ${ruleName}`);
+        },
+        async createPortal(portal) {
+            const env = { PORTAL: portal.name, DIMENSION: portal.dimensionName, GATEWAY: portal.gatewayName, SUBNET_COUNT: String(SUBNET_COUNT) };
+            await call(CREATE_PORTAL, env, `creating portal ${portal.name}`);
+        },
+        async destroyPortal(portalName) {
+            await call(DESTROY_PORTAL, { PORTAL: portalName }, `destroying portal ${portalName}`);
+        },
+        async listPortals() {
+            const result = await call(PRINT_RECORDS, { DIRECTORY: "portals" }, "listing portals");
+            return records(result.stdout).map(([, { name, dimensionName, gatewayName }]) => ({ name, dimensionName, gatewayName }));
+        },
+        async restorePortals({ gatewayName = "", dimensionName = "" }) {
+            return (await call(RESTORE_PORTALS, { GATEWAY: gatewayName, DIMENSION: dimensionName }, "restoring portals")).stderr.trim();
+        },
+    };
+}
+function readyEnv() {
+    return { PROXY_PORT: String(PROXY_PORT), DNS_PORT: String(DNS_PORT), READY_TIMEOUT: String(READY_TIMEOUT_S) };
+}
+function trafficRuleFile({ name, urlMask, action, delayMs }) {
+    return `${JSON.stringify({ name, urlMask, action, delayMs }, null, 2)}\n`;
+}
+const TRUST_GATEWAY_SCRIPT = sh `
+set -eu
+exec 9>/run/hyperbrane-trust.lock
+flock 9
+local_cas=/usr/local/share/ca-certificates
+mkdir -p "$local_cas" /etc/ssl/certs /etc/profile.d
+cert="$local_cas/hyperbrane-gateway-$GATEWAY.crt"
+if [ -n "$GATEWAY_CA" ]; then printf '%s\n' "$GATEWAY_CA" > "$cert"; else rm -f "$cert"; fi
+
+{
+  if [ -f /etc/ca-certificates.conf ]; then
+    grep -v '^[#!]' /etc/ca-certificates.conf | grep . | sed 's|^|/usr/share/ca-certificates/|' | xargs -r -d '\n' cat
+  fi
+  find "$local_cas" -type f -name '*.crt' | sort | xargs -r -d '\n' cat
+} > "$CA_BUNDLE.hyperbrane"
+mv "$CA_BUNDLE.hyperbrane" "$CA_BUNDLE"
+
+find /etc/ssl/certs -maxdepth 1 -type l -lname '*hyperbrane-gateway-*' -delete
+for gateway_cert in "$local_cas"/hyperbrane-gateway-*.crt; do
+  [ -f "$gateway_cert" ] || continue
+  name="\${gateway_cert##*/}"
+  pem="/etc/ssl/certs/\${name%.crt}.pem"
+  ln -sf "$gateway_cert" "$pem"
+  command -v openssl > /dev/null || continue
+  hash="$(openssl x509 -hash -noout -in "$gateway_cert")"
+  index=0
+  while [ -e "/etc/ssl/certs/$hash.$index" ]; do index=$((index + 1)); done
+  ln -s "$pem" "/etc/ssl/certs/$hash.$index"
+done
+
+{ grep -v '^NODE_EXTRA_CA_CERTS=' /etc/environment 2>/dev/null || true; } > /etc/environment.hyperbrane
+if ls "$local_cas"/hyperbrane-gateway-*.crt >/dev/null 2>&1; then
+  echo "NODE_EXTRA_CA_CERTS=$CA_BUNDLE" >> /etc/environment.hyperbrane
+  echo "export NODE_EXTRA_CA_CERTS=$CA_BUNDLE" > /etc/profile.d/hyperbrane-gateway.sh
+else
+  rm -f /etc/profile.d/hyperbrane-gateway.sh
+fi
+mv /etc/environment.hyperbrane /etc/environment
+`;
+export const PORTAL_FUNCTIONS = sh `
+running_pid() {
+  docker inspect -f '{{if .State.Running}}{{.State.Pid}}{{end}}' "$1" 2>/dev/null || true
+}
+
+# shellcheck disable=SC2034
+portal_link() {
+  hash="$(printf '%s' "$1" | sha256sum | cut -c1-8)"
+  DIMENSION_IF="hvd$hash"
+  GATEWAY_IF="hvg$hash"
+  base="10.77.$(($2 >> 6))"
+  offset=$((($2 & 63) << 2))
+  GATEWAY_IP="$base.$((offset + 1))"
+  DIMENSION_IP="$base.$((offset + 2))"
+  ROUTE_METRIC=$((100 + $2))
+}
+
+wire_portal() {
+  portal_link "$1" "$4"
+  for attempt in 1 2; do
+    dimension_pid="$(running_pid "$DIMENSION_PREFIX$2")"
+    gateway_pid="$(running_pid "$GATEWAY_PREFIX$3")"
+    if [ -z "$dimension_pid" ] || [ -z "$gateway_pid" ]; then
+      echo "dimension $2 or gateway $3 is not running" >&2
+      return 1
+    fi
+    if docker run --rm --privileged --pid host --network host --volume /run:/hostrun --init --user root \
+      --label hyperbrane=true --label hyperbrane.helper=wire-portal \
+      -e PORTAL="$1" -e DIMENSION_PID="$dimension_pid" -e GATEWAY_PID="$gateway_pid" \
+      -e DIMENSION_IF="$DIMENSION_IF" -e GATEWAY_IF="$GATEWAY_IF" -e DIMENSION_IP="$DIMENSION_IP" -e GATEWAY_IP="$GATEWAY_IP" \
+      -e ROUTE_METRIC="$ROUTE_METRIC" \
+      "$GATEWAY_IMAGE" hyb-wire-portal > /dev/null; then
+      return 0
+    fi
+    [ "$attempt" = 2 ] || sleep 1
+  done
+  return 1
+}
+
+unwire_portal() {
+  portal_link "$1" "$3"
+  docker exec -u root "$GATEWAY_PREFIX$2" ip link del "$GATEWAY_IF" > /dev/null 2>&1 || true
+}
+
+trust_gateway() {
+  [ -n "$(running_pid "$DIMENSION_PREFIX$1")" ] || return 0
+  ca=""
+  if [ -n "$3" ]; then ca="$(cat "$DATA/gateway-state/$2/mitmproxy/mitmproxy-ca-cert.pem")"; fi
+  docker exec -u root -e GATEWAY="$2" -e GATEWAY_CA="$ca" -e CA_BUNDLE "$DIMENSION_PREFIX$1" sh -c "$TRUST_SCRIPT"
+}
+
+untrust_unless_shared() {
+  for other in "$DATA"/portals/*.json; do
+    [ -f "$other" ] && [ "$other" != "$DATA/portals/$1.json" ] || continue
+    if [ "$(record_text "$other" dimensionName)" = "$2" ] && [ "$(record_text "$other" gatewayName)" = "$3" ]; then return 0; fi
+  done
+  trust_gateway "$2" "$3" ""
+}
+
+ready_portals() {
+  for record in "$DATA"/portals/*.json; do
+    [ -f "$record" ] && [ "$(record_text "$record" state)" = ready ] || continue
+    subnet="$(record_field "$record" subnet)"
+    [ -n "$subnet" ] || continue
+    printf '%s %s %s %s\n' "$(record_text "$record" name)" "$(record_text "$record" dimensionName)" "$(record_text "$record" gatewayName)" "$subnet"
+  done
+}
+
+lock_portal() {
+  mkdir -p "$DATA/portal-locks"
+  exec 8> "$DATA/portal-locks/$1.lock"
+  flock 8
+}
+
+restore_portal() {
+  lock_portal "$1"
+  [ "$(record_text "$DATA/portals/$1.json" state 2> /dev/null)" = ready ] || return 0
+  pids="$(running_pid "$DIMENSION_PREFIX$2") $(running_pid "$GATEWAY_PREFIX$3")"
+  wire_portal "$@" && trust_gateway "$2" "$3" yes && return 0
+  sleep 1
+  [ "$(running_pid "$DIMENSION_PREFIX$2") $(running_pid "$GATEWAY_PREFIX$3")" != "$pids" ] || return 1
+}
+
+restore_portals() {
+  looked="$(mktemp -d)"
+  ready_portals | while read -r portal dimension gateway subnet; do
+    [ -z "$1" ] || [ "$gateway" = "$1" ] || continue
+    [ -z "$2" ] || [ "$dimension" = "$2" ] || continue
+    [ -n "$(running_pid "$DIMENSION_PREFIX$dimension")" ] || continue
+    links="$looked/$gateway.links"
+    [ -f "$links" ] || docker exec "$GATEWAY_PREFIX$gateway" ip -br link > "$links" 2> /dev/null || echo down > "$links"
+    [ "$(cat "$links")" != down ] || continue
+    portal_link "$portal" "$subnet"
+    grep -q "^\${GATEWAY_IF}[@ ]" "$links" && continue
+    echo "$portal $dimension $gateway $subnet" >> "$looked/missing"
+  done
+  if [ -f "$looked/missing" ]; then
+    docker image inspect "$GATEWAY_IMAGE" > /dev/null 2>&1 || exit "$E_NEED_IMAGE"
+    while read -r portal dimension gateway subnet; do
+      (restore_portal "$portal" "$dimension" "$gateway" "$subnet" 2> "$looked/$portal.failed" && rm -f "$looked/$portal.failed") &
+    done < "$looked/missing"
+    wait
+  fi
+  failed=0
+  for failure in "$looked"/*.failed; do
+    [ -f "$failure" ] || continue
+    name="\${failure##*/}"
+    echo "re-wiring portal \${name%.failed} failed: $(cat "$failure")" >&2
+    failed=1
+  done
+  rm -rf "$looked"
+  return "$failed"
+}
+
+# shellcheck disable=SC2034,SC2153
+gateway_paths() {
+  RECORD="$DATA/gateways/$GATEWAY.json"
+  CONTAINER="$GATEWAY_PREFIX$GATEWAY"
+  STATE="$DATA/gateway-state/$GATEWAY"
+  TRANSPORT="$DATA/gateway-transport/$GATEWAY"
+}
+
+# shellcheck disable=SC2034
+transport_running() {
+  TRANSPORT_PID=""
+  TRANSPORT_BUILD=""
+  [ -f "$TRANSPORT/ready" ] || return 1
+  read -r pid build _ < "$TRANSPORT/ready" || return 1
+  grep -q transport "/proc/$pid/cmdline" 2> /dev/null || return 1
+  TRANSPORT_PID="$pid"
+  TRANSPORT_BUILD="$build"
+}
+
+stop_transport() {
+  if transport_running; then
+    kill "$TRANSPORT_PID" 2> /dev/null || true
+    for _ in 1 2 3 4 5 6 7 8 9 10; do kill -0 "$TRANSPORT_PID" 2> /dev/null || break; sleep 0.5; done
+    kill -9 "$TRANSPORT_PID" 2> /dev/null || true
+  fi
+  rm -f "$TRANSPORT/ready"
+}
+
+require_gateway() {
+  gateway_paths
+  [ -f "$RECORD" ] || refuse "$E_NOT_FOUND" "gateway $GATEWAY does not exist"
+}
+
+# shellcheck disable=SC2034
+gateway_container_exists() {
+  info="$(docker inspect -f '{{index .Config.Labels "hyperbrane.gateway"}}|{{.Config.Image}}' "$CONTAINER" 2>/dev/null)" || return 1
+  [ "\${info%%|*}" = "$GATEWAY" ] || refuse "$E_CONFLICT" "container $CONTAINER exists but is not managed by hyperbrane"
+  IMAGE="\${info#*|}"
+}
+
+await_ready() {
+  waited=0
+  until [ -f "$STATE/mitmproxy/mitmproxy-ca-cert.pem" ] && listening="$(docker exec -u root "$CONTAINER" ss -Hln "( sport = :$PROXY_PORT or sport = :$DNS_PORT )" 2> /dev/null)" &&
+    printf '%s\n' "$listening" | grep -q '^tcp' && printf '%s\n' "$listening" | grep -q '^udp'; do
+    if [ "$waited" -ge "$((READY_TIMEOUT * 4))" ]; then
+      refuse 1 "gateway $GATEWAY did not become ready: container $(docker inspect -f '{{.State.Status}}, exit code {{.State.ExitCode}}' "$CONTAINER" 2> /dev/null || echo missing)"
+    fi
+    sleep 0.25
+    waited=$((waited + 1))
+  done
+}
+
+gateway_jq() {
+  if [ -n "$(running_pid "$CONTAINER")" ]; then
+    docker exec -i -e KEY -e FAKE_CHARACTERS "$CONTAINER" jq "$@"
+  else
+    docker image inspect "$GATEWAY_IMAGE" > /dev/null 2>&1 || exit "$E_NEED_IMAGE"
+    docker run --rm -i --network none -e KEY -e FAKE_CHARACTERS "$GATEWAY_IMAGE" jq "$@"
+  fi
+}
+`;
+const PRINT_RECORDS = sh `
+print_records "$DATA/$DIRECTORY"
+`;
+const CREATE_GATEWAY = sh `
+set -eu
+gateway_paths
+if gateway_container_exists; then :; fi
+mkdir -p "$DATA/gateways"
+[ -f "$RECORD" ] || printf '{\n  "name": "%s",\n  "state": "creating"\n}\n' "$GATEWAY" | write_new "$RECORD"
+mkdir -p "$STATE/upstreams" "$STATE/credentials" "$STATE/traffic-rules" "$STATE/traffic-responses" "$STATE/mitmproxy"
+tab="$(printf '\t')"
+printf '%s\n' "$UPSTREAMS" | while IFS="$tab" read -r name definition; do
+  [ -z "$name" ] || printf '%s\n' "$definition" | write_whole "$STATE/upstreams/$name.json"
+done
+docker image inspect "$GATEWAY_IMAGE" > /dev/null 2>&1 || exit "$E_NEED_IMAGE"
+
+if gateway_container_exists && [ "$IMAGE" != "$GATEWAY_IMAGE" ]; then docker rm -f "$CONTAINER" > /dev/null; fi
+if ! gateway_container_exists; then
+  if ! created="$(docker create --name "$CONTAINER" --hostname "$CONTAINER" \
+    --label hyperbrane=true --label "hyperbrane.version=$VERSION" --label "hyperbrane.gateway=$GATEWAY" \
+    --volume "$STATE:$STATE_PATH" --cap-add NET_ADMIN --network bridge --init --restart unless-stopped \
+    "$GATEWAY_IMAGE" 2>&1)"; then
+    case "$created" in
+      *"already in use"*) ;;
+      *) refuse 1 "$created" ;;
+    esac
+    waited=0
+    until gateway_container_exists; do
+      [ "$waited" -lt 50 ] || refuse 1 "$created"
+      sleep 0.1
+      waited=$((waited + 1))
+    done
+  fi
+fi
+docker start "$CONTAINER" > /dev/null
+await_ready
+grep -q '"state": "ready"' "$RECORD" || printf '{\n  "name": "%s",\n  "state": "ready"\n}\n' "$GATEWAY" | write_whole "$RECORD"
+restore_portals "$GATEWAY" ""
+`;
+const DESTROY_GATEWAY = sh `
+set -eu
+gateway_paths
+attached=""
+for portal in "$DATA"/portals/*.json; do
+  [ -f "$portal" ] && [ "$(record_text "$portal" gatewayName)" = "$GATEWAY" ] || continue
+  attached="$attached\${attached:+, }$(record_text "$portal" name)"
+done
+[ -z "$attached" ] || refuse "$E_CONFLICT" "gateway $GATEWAY still has portals: $attached"
+stop_transport
+rm -rf "$TRANSPORT"
+if gateway_container_exists; then
+  if ! removed="$(docker rm -f "$CONTAINER" 2>&1)" && docker inspect "$CONTAINER" > /dev/null 2>&1; then refuse 1 "$removed"; fi
+fi
+rm -rf "$STATE"
+rm -f "$RECORD"
+`;
+const RESTART_GATEWAY = sh `
+set -eu
+require_gateway
+gateway_container_exists || refuse "$E_NOT_FOUND" "gateway $GATEWAY has no container; create it again"
+if [ -n "$(ready_portals)" ]; then docker image inspect "$GATEWAY_IMAGE" > /dev/null 2>&1 || exit "$E_NEED_IMAGE"; fi
+docker restart "$CONTAINER" > /dev/null
+await_ready
+restore_portals "$GATEWAY" ""
+`;
+const START_TRANSPORT = sh `
+set -eu
+require_gateway
+mkdir -p "$TRANSPORT"
+chmod 700 "$TRANSPORT"
+exec 9> "$TRANSPORT/lock"
+flock -w 120 9
+if [ -z "$RESTART" ] && transport_running && [ "$TRANSPORT_BUILD" = "$BUILD" ] &&
+  [ "$(cat "$TRANSPORT/port" 2> /dev/null)" = "$PORT" ] && [ "$(cat "$TRANSPORT/secret" 2> /dev/null)" = "$SECRET" ]; then
+  exit 0
+fi
+[ -f "$TRANSPORT/transport-$BUILD.js" ] || { printf '%s\n' "$TRANSPORT"; exit "$E_NEED_BUNDLE"; }
+
+bun=""
+if command -v bun > /dev/null 2>&1 && [ "$(bun --version 2> /dev/null)" = "$BUN_VERSION" ]; then bun="$(command -v bun)"; fi
+if [ -z "$bun" ]; then
+  bun="$DATA/bun/$BUN_VERSION/bun"
+  if [ ! -x "$bun" ]; then
+    case "$(uname -m)" in
+      x86_64 | amd64) arch=x64 ;;
+      aarch64 | arm64) arch=aarch64 ;;
+      *) refuse 1 "there is no bun build for $(uname -m)" ;;
+    esac
+    mkdir -p "\${bun%/*}"
+    zip="$bun.$$.zip"
+    url="https://github.com/oven-sh/bun/releases/download/bun-v$BUN_VERSION/bun-linux-$arch.zip"
+    if command -v curl > /dev/null 2>&1; then curl -fsSL -o "$zip" "$url"; else wget -qO "$zip" "$url"; fi
+    if command -v unzip > /dev/null 2>&1; then
+      unzip -p "$zip" "bun-linux-$arch/bun" > "$bun.$$"
+    else
+      python3 -c 'import sys, zipfile; sys.stdout.buffer.write(zipfile.ZipFile(sys.argv[1]).read(sys.argv[2]))' "$zip" "bun-linux-$arch/bun" > "$bun.$$"
+    fi
+    chmod 755 "$bun.$$"
+    mv -f "$bun.$$" "$bun"
+    rm -f "$zip"
+  fi
+fi
+
+umask 077
+printf '%s' "$SECRET" > "$TRANSPORT/secret.$$"
+mv -f "$TRANSPORT/secret.$$" "$TRANSPORT/secret"
+printf '%s' "$PORT" > "$TRANSPORT/port"
+stop_transport
+HYB_TRANSPORT_DIR="$TRANSPORT" HYB_TRANSPORT_BUILD="$BUILD" HYB_TRANSPORT_PORT="$PORT" HYB_GATEWAY="$GATEWAY" HYB_DATA="$DATA" \
+  setsid nohup "$bun" "$TRANSPORT/transport-$BUILD.js" >> "$TRANSPORT/log" 2>&1 < /dev/null 9>&- &
+waited=0
+until transport_running && [ "$TRANSPORT_BUILD" = "$BUILD" ]; do
+  if [ "$waited" -ge 100 ]; then
+    echo "gateway $GATEWAY's transport worker did not come up:" >&2
+    tail -c 2000 "$TRANSPORT/log" >&2
+    exit 1
+  fi
+  sleep 0.2
+  waited=$((waited + 1))
+done
+find "$TRANSPORT" -maxdepth 1 -name 'transport-*.js' ! -name "transport-$BUILD.js" -exec rm -f {} + 2> /dev/null || true
+`;
+const WRITE_STATE = sh `
+set -eu
+require_gateway
+printf '%s' "$CONTENT" | write_whole "$STATE/$FILE"
+`;
+const REMOVE_STATE = sh `
+set -eu
+gateway_paths
+rm -f "$STATE/$FILE"
+`;
+const LIST_STATE = sh `
+set -eu
+require_gateway
+print_records "$STATE/$DIRECTORY"
+`;
+const REMOVE_UPSTREAM = sh `
+set -eu
+gateway_paths
+rm -f "$STATE/credentials/$UPSTREAM.oauth.json" "$STATE/credentials/$UPSTREAM.api-keys.json"
+rm -f "$STATE/upstreams/$UPSTREAM.json"
+`;
+const LIST_CREDENTIALS = sh `
+set -eu
+require_gateway
+for definition in "$STATE"/upstreams/*.json; do
+  [ -f "$definition" ] || continue
+  name="\${definition##*/}"
+  name="\${name%.json}"
+  oauth=0
+  if [ -f "$STATE/credentials/$name.oauth.json" ]; then oauth=1; fi
+  printf '%s %s\n' "$name" "$oauth"
+  cat "$STATE/credentials/$name.api-keys.json" 2> /dev/null || echo null
+  printf '\n\036\n'
+done
+`;
+const SET_API_KEY = sh `
+set -eu
+require_gateway
+definition="$STATE/upstreams/$UPSTREAM.json"
+[ -f "$definition" ] || refuse "$E_NOT_FOUND" "upstream $UPSTREAM does not exist on gateway $GATEWAY"
+keys="$STATE/credentials/$UPSTREAM.api-keys.json"
+stored="$(cat "$keys" 2> /dev/null || echo null)"
+# shellcheck disable=SC2016
+merged="$(printf '%s\n%s\n' "$(cat "$definition")" "$stored" | gateway_jq -rs --arg name "$KEY_NAME" '
+  if .[0].modes.apiKey == null then "none" else
+    (.[0].modes.apiKey.fake.prefix // "") as $prefix
+    | (.[1] // {keys: {}}) as $stored
+    | ($stored.keys[$name].fake // ($prefix + $ENV.FAKE_CHARACTERS[0:([($ENV.KEY | length) - ($prefix | length), 16] | max)])) as $fake
+    | $fake, ($stored | .keys[$name] = {key: $ENV.KEY, fake: $fake} | tojson)
+  end')"
+fake="$(printf '%s\n' "$merged" | head -n 1)"
+[ "$fake" != none ] || refuse "$E_INVALID" "upstream $UPSTREAM has no API key mode"
+mkdir -p "$STATE/credentials"
+printf '%s\n' "$merged" | tail -n +2 | write_whole "$keys"
+printf '%s\n' "$fake"
+`;
+const DELETE_API_KEY = sh `
+set -eu
+require_gateway
+[ -f "$STATE/upstreams/$UPSTREAM.json" ] || refuse "$E_NOT_FOUND" "upstream $UPSTREAM does not exist on gateway $GATEWAY"
+keys="$STATE/credentials/$UPSTREAM.api-keys.json"
+[ -f "$keys" ] || exit 0
+# shellcheck disable=SC2016
+left="$(gateway_jq -r --arg name "$KEY_NAME" 'del(.keys[$name]) | if (.keys | length) == 0 then "" else tojson end' < "$keys")"
+if [ -z "$left" ]; then rm -f "$keys"; else printf '%s\n' "$left" | write_whole "$keys"; fi
+`;
+const CREATE_TRAFFIC_RULE = sh `
+set -eu
+require_gateway
+rule_file="$STATE/traffic-rules/$RULE.json"
+mkdir -p "$STATE/traffic-rules"
+printf '%s' "$CONTENT" | write_new "$rule_file"
+printf '%s' "$CONTENT" | cmp -s - "$rule_file" || refuse "$E_CONFLICT" "traffic rule $RULE already exists with a different spec"
+`;
+const UPDATE_TRAFFIC_RULE = sh `
+set -eu
+require_gateway
+rule_file="$STATE/traffic-rules/$RULE.json"
+[ -f "$rule_file" ] || refuse "$E_NOT_FOUND" "traffic rule $RULE does not exist on gateway $GATEWAY"
+printf '%s' "$CONTENT" | write_whole "$rule_file"
+`;
+const DELETE_TRAFFIC_RULE = sh `
+set -eu
+gateway_paths
+rm -f "$STATE/traffic-rules/$RULE.json" "$STATE/traffic-responses/$RULE.json"
+`;
+const RESPOND_TRAFFIC_RULE = sh `
+set -eu
+require_gateway
+rule_file="$STATE/traffic-rules/$RULE.json"
+[ -f "$rule_file" ] || refuse "$E_NOT_FOUND" "traffic rule $RULE does not exist on gateway $GATEWAY"
+[ "$(record_text "$rule_file" action)" = ASK ] || refuse "$E_INVALID" "traffic rule $RULE is not an ASK rule"
+mkdir -p "$STATE/traffic-responses"
+printf '%s' "$CONTENT" | write_whole "$STATE/traffic-responses/$RULE.json"
+`;
+const CREATE_PORTAL = sh `
+set -eu
+require_running() {
+  info="$(docker inspect -f "{{index .Config.Labels \"hyperbrane.$1\"}}|{{.State.Running}}" "$2" 2> /dev/null)" || refuse "$E_NOT_FOUND" "$1 $3 does not exist"
+  [ "\${info%|*}" = "$3" ] || refuse "$E_NOT_FOUND" "$1 $3 does not exist"
+  [ "\${info#*|}" = true ] || refuse "$E_CONFLICT" "$1 $3 is not running"
+}
+gateway_record="$DATA/gateways/$GATEWAY.json"
+[ -f "$gateway_record" ] && [ "$(record_text "$gateway_record" state)" = ready ] || refuse "$E_NOT_FOUND" "gateway $GATEWAY is not ready"
+require_running gateway "$GATEWAY_PREFIX$GATEWAY" "$GATEWAY"
+require_running dimension "$DIMENSION_PREFIX$DIMENSION" "$DIMENSION"
+docker image inspect "$GATEWAY_IMAGE" > /dev/null 2>&1 || exit "$E_NEED_IMAGE"
+
+record="$DATA/portals/$PORTAL.json"
+lock_portal "$PORTAL"
+mkdir -p "$DATA/portals" "$DATA/portal-subnets"
+printf '{\n  "name": "%s",\n  "dimensionName": "%s",\n  "gatewayName": "%s",\n  "state": "creating"\n}\n' "$PORTAL" "$DIMENSION" "$GATEWAY" | write_new "$record"
+[ "$(record_text "$record" state)" != destroying ] || refuse "$E_CONFLICT" "portal $PORTAL is being destroyed"
+if [ "$(record_text "$record" dimensionName)" != "$DIMENSION" ] || [ "$(record_text "$record" gatewayName)" != "$GATEWAY" ]; then
+  refuse "$E_CONFLICT" "portal $PORTAL already exists with a different spec"
+fi
+
+subnet="$(record_field "$record" subnet)"
+if [ -z "$subnet" ]; then
+  subnet=0
+  until [ "$(record_text "$DATA/portal-subnets/$subnet.json" portalName 2> /dev/null)" = "$PORTAL" ]; do
+    if [ -e "$DATA/portal-subnets/$subnet.json" ]; then
+      subnet=$((subnet + 1))
+      continue
+    fi
+    [ "$subnet" -lt "$SUBNET_COUNT" ] || refuse "$E_CONFLICT" "no portal subnets left"
+    printf '{\n  "subnet": %s,\n  "portalName": "%s"\n}\n' "$subnet" "$PORTAL" | write_new "$DATA/portal-subnets/$subnet.json"
+  done
+  sed 's/^  "state": \(.*\)$/  "state": \1,\n  "subnet": '"$subnet"'/' "$record" | write_whole "$record"
+fi
+
+wire_portal "$PORTAL" "$DIMENSION" "$GATEWAY" "$subnet" || refuse 1 "wiring portal $PORTAL failed"
+trust_gateway "$DIMENSION" "$GATEWAY" yes
+sed 's/^  "state": "creating"/  "state": "ready"/' "$record" | write_whole "$record"
+`;
+const DESTROY_PORTAL = sh `
+set -eu
+record="$DATA/portals/$PORTAL.json"
+[ -f "$record" ] || exit 0
+lock_portal "$PORTAL"
+dimension="$(record_text "$record" dimensionName)"
+gateway="$(record_text "$record" gatewayName)"
+subnet="$(record_field "$record" subnet)"
+sed 's/^  "state": "[a-z]*"/  "state": "destroying"/' "$record" | write_whole "$record"
+if [ -n "$subnet" ]; then
+  unwire_portal "$PORTAL" "$gateway" "$subnet"
+  rm -f "$DATA/portal-subnets/$subnet.json"
+fi
+untrust_unless_shared "$PORTAL" "$dimension" "$gateway"
+rm -f "$record" "$DATA/portal-locks/$PORTAL.lock"
+`;
+const RESTORE_PORTALS = sh `
+restore_portals "$GATEWAY" "$DIMENSION" || true
+`;

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

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

package/dist/portal-gateway/gatewayClient.js

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