@ouro.bot/cli 0.1.0-alpha.954 → 0.1.0-alpha.956

package/changelog.json

@@ -1,6 +1,20 @@
 {
   "_note": "This changelog is maintained as part of the PR/version-bump workflow. Agent-curated, not auto-generated. Agents read this file directly via read_file to understand what changed between versions.",
   "versions": [
+    {
+      "version": "0.1.0-alpha.956",
+      "changes": [
+        "A new credit gateway (ouro gateway serve) lets agents use one master key while it spends several Anthropic API keys in a fixed order, moving to the next key only when one runs out of credits, with a health page and a runbook for running it next to the Butler on Unraid.",
+        "The Anthropic provider can now use a plain API key and a custom base URL (ouro auth --provider anthropic --api-key-file <path> --base-url <url>, which reads the key from a file or standard input and never from the command line), so an agent can run on API credits through the credit gateway; the existing setup-token login works as before.",
+        "The credit gateway refuses any request path that would send a key to a host other than the Anthropic API."
+      ]
+    },
+    {
+      "version": "0.1.0-alpha.955",
+      "changes": [
+        "iMessage no longer loses a reply that fails to send. When Slugger's reply times out or otherwise fails at BlueBubbles, your message stays pending; about ten minutes later a recovery pass checks the chat, and if the reply did not arrive after all, Slugger answers again. The message is marked handled only once a reply goes through. After three failed sends it is given up on with an error in the logs, so one stuck message cannot use up the day's recovery budget. If Slugger had already said something partway through that turn, the message is not retried, so you never see that part twice."
+      ]
+    },
     {
       "version": "0.1.0-alpha.954",
       "changes": [

package/deploy/unraid/credit-gateway.md

@@ -0,0 +1,95 @@
+# Credit gateway runbook
+
+The credit gateway lets the Butler run on the API credits of several Claude Max plans through one key. Agents present a single master key; the gateway holds the real Anthropic API keys and spends them in a fixed order: it uses the first key until the API says that key's credit balance is too low, then the second, then the third. It never spreads load across keys.
+
+It runs from the same image as the Butler (no separate image), as a second container named `ouro-credit-gateway`. Both containers use host networking, so the gateway listens on `127.0.0.1:8787` and the Butler reaches it at `http://127.0.0.1:8787`. Nothing is published to the network.
+
+## How it behaves
+
+- `master.key` in the keys folder is the key clients must send, as `x-api-key` or `Authorization: Bearer`. A wrong or missing key gets HTTP 401 `invalid x-api-key`.
+- Every other `*.key` file is an upstream Anthropic API key. The gateway uses them in file-name order (`acct1.key`, `acct2.key`, `acct3.key`). The label in logs and health is the file name without `.key`. Key contents are never logged.
+- The gateway reads the keys once at start. Restart the container after changing a key file.
+- When the API answers HTTP 400, 402 or 403 with "credit balance is too low", the gateway skips that key for the cooldown (60 minutes by default), logs `gateway: <label> out of credits; moving on`, and retries the same request with the next key. After the cooldown it tries the key again, which is how a key comes back once its org's credits refresh. A rejected credit check is not billed.
+- The skip list is saved in `gateway-state.json` in the keys folder (mode 0600), so a restart remembers it. Delete that file to retry every key at once.
+- When every key is out of credits, clients get HTTP 400 with the API's last credit-balance error.
+- If the API cannot be reached, clients get HTTP 502 and the gateway does not move to the next key.
+- Every request logs one line: `gateway: <label> <method> <path> <status> <ms>ms`. Read them with `docker logs ouro-credit-gateway`.
+
+## One-time setup (as root on the Unraid host)
+
+1. Create the keys folder, owned by the image's user (UID/GID 10001) and closed to everyone else:
+
+   ```sh
+   install -d -o 10001 -g 10001 -m 0700 /mnt/user/appdata/credit-gateway /mnt/user/appdata/credit-gateway/keys
+   ```
+
+2. Put one upstream API key per account in the folder, one key per file, each file mode 0600. Copy the key files in rather than pasting keys on the command line, so they stay out of shell history:
+
+   ```sh
+   cd /mnt/user/appdata/credit-gateway/keys
+   install -o 10001 -g 10001 -m 0600 /path/to/acct1.key acct1.key
+   install -o 10001 -g 10001 -m 0600 /path/to/acct2.key acct2.key
+   install -o 10001 -g 10001 -m 0600 /path/to/acct3.key acct3.key
+   ```
+
+3. Generate the master key:
+
+   ```sh
+   cd /mnt/user/appdata/credit-gateway/keys
+   (umask 077; printf 'ouro-gw-%s\n' "$(openssl rand -hex 32)" > master.key)
+   chown 10001:10001 master.key
+   ```
+
+4. Check the result. Every file should be `-rw------- 10001 10001`:
+
+   ```sh
+   ls -ln /mnt/user/appdata/credit-gateway/keys
+   ```
+
+The folder must stay writable by UID 10001, because the gateway saves `gateway-state.json` there.
+
+## Run the gateway
+
+Use the same image tag the Butler runs (the `<Repository>` in `sanctuary.xml`). The image's entrypoint starts the agent daemon, so override it with `--entrypoint node`. The image's built-in health check probes the agent, so replace it with a check of the gateway's own health URL:
+
+```sh
+docker run -d --name ouro-credit-gateway \
+  --network host \
+  --restart unless-stopped \
+  --entrypoint node \
+  -v /mnt/user/appdata/credit-gateway/keys:/keys \
+  --health-cmd 'curl -fsS http://127.0.0.1:8787/health || exit 1' \
+  --health-interval 30s --health-timeout 5s --health-retries 3 \
+  ghcr.io/ourostack/ouroboros-butler:<same tag as ouro-butler> \
+  /opt/ouro/dist/heart/daemon/ouro-entry.js gateway serve --keys-dir /keys --host 127.0.0.1 --port 8787
+```
+
+Port 8787 is also the default port of Readarr and its forks (such as Bookshelf). If `ss -ltn | grep 8787` shows it in use, pick a free port (for example 8788) and use it in `--port`, the health check and the Butler's `--base-url`.
+
+Optional flags after `gateway serve`: `--cooldown-minutes <n>` (default 60), `--state <path>` (default `<keys-dir>/gateway-state.json`), `--upstream <url>` (default `https://api.anthropic.com`).
+
+## Check it
+
+```sh
+docker inspect --format '{{.State.Status}} {{.State.Health.Status}}' ouro-credit-gateway
+curl -fsS http://127.0.0.1:8787/health
+docker logs --tail 20 ouro-credit-gateway
+```
+
+`/health` needs no key and returns, for example, `{"ok":true,"keys":[{"label":"acct1","available":true},{"label":"acct2","available":false,"skipUntil":"2026-11-01T10:00:00.000Z"},{"label":"acct3","available":true}]}`.
+
+## Point the Butler at it
+
+Store the master key and the gateway URL as the Butler's Anthropic credentials (API-key mode). The key is read from a file or standard input, never from the command line:
+
+```sh
+docker exec -i -u 10001 ouro-butler node /opt/ouro/dist/heart/daemon/ouro-entry.js \
+  auth --agent sanctuary --provider anthropic --api-key-file /dev/stdin --base-url http://127.0.0.1:8787 \
+  < /mnt/user/appdata/credit-gateway/keys/master.key
+```
+
+Then select an Anthropic model for the Butler's lanes with `ouro use`. In API-key mode the agent sends a plain API key, with no Claude Code identity headers, no Claude Code system preamble and no token refresh.
+
+## Change or rotate keys
+
+Replace the file (keep owner 10001 and mode 0600), then `docker restart ouro-credit-gateway`. After rotating `master.key`, run the `auth` step above again so the Butler sends the new master key.

package/deploy/unraid/sanctuary.ouro/bundle-meta.json

@@ -1,5 +1,5 @@
 {
-  "runtimeVersion": "0.1.0-alpha.954",
+  "runtimeVersion": "0.1.0-alpha.956",
   "bundleSchemaVersion": 3,
   "lastUpdated": "2026-09-03T00:00:00.000Z"
 }

package/deploy/unraid/sanctuary.xml

@@ -1,7 +1,7 @@
 <?xml version="1.0"?>
 <Container version="2">
   <Name>ouro-butler</Name>
-  <Repository>ghcr.io/ourostack/ouroboros-butler:0.1.0-alpha.954</Repository>
+  <Repository>ghcr.io/ourostack/ouroboros-butler:0.1.0-alpha.956</Repository>
   <Registry>https://github.com/ourostack/ouroboros/pkgs/container/ouroboros-butler</Registry>
   <Network>host</Network>
   <Shell>sh</Shell>

package/dist/gateway/keys.js

@@ -0,0 +1,117 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadGatewayKeys = loadGatewayKeys;
+exports.loadGatewayState = loadGatewayState;
+exports.saveGatewayState = saveGatewayState;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const runtime_1 = require("../nerves/runtime");
+const MASTER_KEY_FILE = "master.key";
+const KEY_SUFFIX = ".key";
+function readTrimmed(filePath) {
+    try {
+        return fs.readFileSync(filePath, "utf8").trim();
+    }
+    catch {
+        return "";
+    }
+}
+/**
+ * Reads the master key and the upstream keys from a directory, once. Every `*.key` file other than
+ * `master.key` is an upstream key; the gateway drains them in file-name order.
+ */
+function loadGatewayKeys(keysDir) {
+    let entries;
+    try {
+        entries = fs.readdirSync(keysDir);
+    }
+    catch (error) {
+        /* v8 ignore next -- defensive: fs always throws Error instances @preserve */
+        const reason = error instanceof Error ? error.message : String(error);
+        throw new Error(`gateway: cannot read keys directory ${keysDir}: ${reason}`);
+    }
+    const masterKey = readTrimmed(path.join(keysDir, MASTER_KEY_FILE));
+    if (!masterKey)
+        throw new Error(`gateway: ${path.join(keysDir, MASTER_KEY_FILE)} is missing or empty`);
+    const upstream = [];
+    for (const name of entries.filter((entry) => entry.endsWith(KEY_SUFFIX) && entry !== MASTER_KEY_FILE).sort()) {
+        const key = readTrimmed(path.join(keysDir, name));
+        if (!key)
+            throw new Error(`gateway: upstream key file ${path.join(keysDir, name)} is empty`);
+        upstream.push({ label: name.slice(0, -KEY_SUFFIX.length), key });
+    }
+    if (upstream.length === 0)
+        throw new Error(`gateway: no upstream *.key files in ${keysDir} (besides master.key)`);
+    (0, runtime_1.emitNervesEvent)({
+        component: "gateway",
+        event: "gateway.keys_loaded",
+        message: "credit gateway keys loaded",
+        meta: { keysDir, labels: upstream.map((entry) => entry.label) },
+    });
+    return { masterKey, upstream };
+}
+/** Loads the skip list. A missing or corrupt file starts empty; entries that are not valid times are dropped. */
+function loadGatewayState(statePath) {
+    const exhausted = {};
+    let parsed;
+    try {
+        parsed = JSON.parse(fs.readFileSync(statePath, "utf8"));
+    }
+    catch {
+        return { exhausted };
+    }
+    const raw = parsed && typeof parsed === "object" ? parsed.exhausted : undefined;
+    if (raw && typeof raw === "object" && !Array.isArray(raw)) {
+        for (const [label, until] of Object.entries(raw)) {
+            if (typeof until === "string" && Number.isFinite(Date.parse(until)))
+                exhausted[label] = until;
+        }
+    }
+    return { exhausted };
+}
+/** Writes the skip list with mode 0600, through a temporary file so a crash never leaves half a file. */
+function saveGatewayState(statePath, state) {
+    const tmpPath = `${statePath}.${process.pid}.tmp`;
+    fs.writeFileSync(tmpPath, `${JSON.stringify(state, null, 2)}\n`, { mode: 0o600 });
+    fs.chmodSync(tmpPath, 0o600);
+    fs.renameSync(tmpPath, statePath);
+    (0, runtime_1.emitNervesEvent)({
+        component: "gateway",
+        event: "gateway.state_saved",
+        message: "credit gateway state saved",
+        meta: { statePath, exhausted: Object.keys(state.exhausted) },
+    });
+}

package/dist/gateway/server.js

@@ -0,0 +1,429 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GATEWAY_MAX_REQUEST_BYTES = exports.GATEWAY_DEFAULT_COOLDOWN_MS = exports.GATEWAY_DEFAULT_UPSTREAM = exports.GATEWAY_DEFAULT_PORT = exports.GATEWAY_DEFAULT_HOST = void 0;
+exports.isCreditExhaustedBody = isCreditExhaustedBody;
+exports.creditGatewayOptionsFromCli = creditGatewayOptionsFromCli;
+exports.startCreditGateway = startCreditGateway;
+exports.waitForShutdownSignal = waitForShutdownSignal;
+exports.runCreditGatewayCommand = runCreditGatewayCommand;
+const http = __importStar(require("node:http"));
+const https = __importStar(require("node:https"));
+const path = __importStar(require("node:path"));
+const zlib = __importStar(require("node:zlib"));
+const node_crypto_1 = require("node:crypto");
+const node_stream_1 = require("node:stream");
+const runtime_1 = require("../nerves/runtime");
+const keys_1 = require("./keys");
+exports.GATEWAY_DEFAULT_HOST = "127.0.0.1";
+exports.GATEWAY_DEFAULT_PORT = 8787;
+exports.GATEWAY_DEFAULT_UPSTREAM = "https://api.anthropic.com";
+exports.GATEWAY_DEFAULT_COOLDOWN_MS = 60 * 60 * 1000;
+exports.GATEWAY_MAX_REQUEST_BYTES = 32 * 1024 * 1024;
+const CREDIT_LOW_PHRASE = "credit balance is too low";
+const CREDIT_CHECK_STATUSES = new Set([400, 402, 403]);
+const HOP_BY_HOP_HEADERS = new Set([
+    "connection",
+    "keep-alive",
+    "proxy-authenticate",
+    "proxy-authorization",
+    "proxy-connection",
+    "te",
+    "trailer",
+    "transfer-encoding",
+    "upgrade",
+]);
+class RequestTooLargeError extends Error {
+}
+function anthropicError(type, message) {
+    return JSON.stringify({ type: "error", error: { type, message } });
+}
+/* v8 ignore start -- defensive: Node and the HTTP stack always throw Error instances @preserve */
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/* v8 ignore stop */
+function digest(value) {
+    return (0, node_crypto_1.createHash)("sha256").update(value).digest();
+}
+/** Compares digests so the comparison takes the same time whatever the presented key's length. */
+function matchesMasterKey(presented, masterDigest) {
+    if (!presented)
+        return false;
+    return (0, node_crypto_1.timingSafeEqual)(digest(presented), masterDigest);
+}
+function presentedKey(req) {
+    const apiKey = req.headers["x-api-key"];
+    if (typeof apiKey === "string" && apiKey.trim())
+        return apiKey.trim();
+    const bearer = /^Bearer\s+(.+)$/i.exec(req.headers.authorization ?? "");
+    return bearer ? bearer[1].trim() : undefined;
+}
+function readRequestBody(req, maxBytes) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        let size = 0;
+        req.on("data", (chunk) => {
+            size += chunk.length;
+            if (size > maxBytes) {
+                reject(new RequestTooLargeError());
+                req.pause();
+                return;
+            }
+            chunks.push(chunk);
+        });
+        req.on("end", () => resolve(Buffer.concat(chunks)));
+        req.on("error", reject);
+    });
+}
+function readAll(stream) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        stream.on("data", (chunk) => chunks.push(chunk));
+        stream.on("end", () => resolve(Buffer.concat(chunks)));
+        stream.on("error", reject);
+    });
+}
+function forwardedRequestHeaders(req, upstreamKey, bodyLength) {
+    const headers = {};
+    for (const [name, value] of Object.entries(req.headers)) {
+        if (HOP_BY_HOP_HEADERS.has(name) || name === "host" || name === "content-length" || name === "x-api-key" || name === "authorization")
+            continue;
+        headers[name] = value;
+    }
+    headers["x-api-key"] = upstreamKey;
+    if (bodyLength > 0)
+        headers["content-length"] = String(bodyLength);
+    return headers;
+}
+function responseHeaders(headers) {
+    const result = {};
+    for (const [name, value] of Object.entries(headers)) {
+        if (HOP_BY_HOP_HEADERS.has(name))
+            continue;
+        result[name] = value;
+    }
+    return result;
+}
+/** Decodes a compressed body for inspection only; the client still gets the original bytes. */
+function decodeForInspection(body, encoding) {
+    try {
+        const normalized = (encoding ?? "").trim().toLowerCase();
+        if (normalized === "gzip" || normalized === "x-gzip")
+            return zlib.gunzipSync(body).toString("utf8");
+        if (normalized === "deflate")
+            return zlib.inflateSync(body).toString("utf8");
+        if (normalized === "br")
+            return zlib.brotliDecompressSync(body).toString("utf8");
+        return body.toString("utf8");
+    }
+    catch {
+        return body.toString("utf8");
+    }
+}
+function isCreditExhaustedBody(body, encoding) {
+    return decodeForInspection(body, encoding).toLowerCase().includes(CREDIT_LOW_PHRASE);
+}
+function upstreamUrl(base, requestUrl) {
+    const prefix = base.pathname.replace(/\/+$/, "");
+    return new URL(`${prefix}${requestUrl}`, base.origin);
+}
+function sendUpstream(target, method, headers, body) {
+    return new Promise((resolve, reject) => {
+        const transport = target.protocol === "https:" ? https : http;
+        const request = transport.request(target, { method, headers }, (response) => resolve({ response, request }));
+        request.on("error", reject);
+        request.end(body.length > 0 ? body : undefined);
+    });
+}
+function writeBuffered(res, buffered) {
+    res.writeHead(buffered.status, { ...buffered.headers, "content-length": String(buffered.body.length) });
+    res.end(buffered.body);
+}
+function writeJsonError(res, status, type, message) {
+    const body = Buffer.from(anthropicError(type, message));
+    writeBuffered(res, { status, headers: { "content-type": "application/json" }, body });
+}
+/** Maps `ouro gateway serve` flags to gateway options. */
+function creditGatewayOptionsFromCli(command) {
+    return {
+        keysDir: command.keysDir,
+        ...(command.statePath ? { statePath: command.statePath } : {}),
+        ...(command.host ? { host: command.host } : {}),
+        ...(command.port !== undefined ? { port: command.port } : {}),
+        ...(command.upstream ? { upstream: command.upstream } : {}),
+        ...(command.cooldownMinutes !== undefined ? { cooldownMs: command.cooldownMinutes * 60 * 1000 } : {}),
+    };
+}
+/* v8 ignore start -- the default log writes to the real stderr; tests inject log @preserve */
+function defaultLog(line) {
+    process.stderr.write(`${line}\n`);
+}
+/* v8 ignore stop */
+/**
+ * Starts the credit gateway: a byte-passthrough proxy to the Anthropic API that accepts one master key
+ * and spends the upstream keys in a fixed order, moving to the next key only when the current one
+ * reports that its credit balance is too low.
+ */
+async function startCreditGateway(options) {
+    const keys = (0, keys_1.loadGatewayKeys)(options.keysDir);
+    const statePath = options.statePath ?? path.join(options.keysDir, "gateway-state.json");
+    const state = (0, keys_1.loadGatewayState)(statePath);
+    const host = options.host ?? exports.GATEWAY_DEFAULT_HOST;
+    const upstreamBase = new URL(options.upstream ?? exports.GATEWAY_DEFAULT_UPSTREAM);
+    const cooldownMs = options.cooldownMs ?? exports.GATEWAY_DEFAULT_COOLDOWN_MS;
+    const maxRequestBytes = options.maxRequestBytes ?? exports.GATEWAY_MAX_REQUEST_BYTES;
+    const now = options.now ?? Date.now;
+    const log = options.log ?? defaultLog;
+    const masterDigest = digest(keys.masterKey);
+    function persist() {
+        try {
+            (0, keys_1.saveGatewayState)(statePath, state);
+        }
+        catch (error) {
+            (0, runtime_1.emitNervesEvent)({
+                level: "warn",
+                component: "gateway",
+                event: "gateway.state_save_error",
+                message: "credit gateway could not save its state",
+                meta: { statePath, error: errorMessage(error) },
+            });
+        }
+    }
+    /** Returns the skip-until time for a label, or undefined when the key is usable. Expired entries are dropped. */
+    function skipUntil(label) {
+        const until = state.exhausted[label];
+        if (!until)
+            return undefined;
+        if (Date.parse(until) > now())
+            return until;
+        delete state.exhausted[label];
+        persist();
+        return undefined;
+    }
+    function markExhausted(entry) {
+        state.exhausted[entry.label] = new Date(now() + cooldownMs).toISOString();
+        persist();
+        log(`gateway: ${entry.label} out of credits; moving on`);
+        (0, runtime_1.emitNervesEvent)({
+            level: "warn",
+            component: "gateway",
+            event: "gateway.key_exhausted",
+            message: "credit gateway key is out of credits",
+            meta: { label: entry.label, skipUntil: state.exhausted[entry.label] },
+        });
+    }
+    function logRequest(label, method, pathname, status, startedAt) {
+        const ms = now() - startedAt;
+        log(`gateway: ${label} ${method} ${pathname} ${status} ${ms}ms`);
+        (0, runtime_1.emitNervesEvent)({
+            component: "gateway",
+            event: "gateway.request",
+            message: "credit gateway request",
+            meta: { label, method, path: pathname, status, ms },
+        });
+    }
+    async function handle(req, res) {
+        const startedAt = now();
+        /* v8 ignore start -- Node always supplies url and method for accepted HTTP requests @preserve */
+        const requestUrl = req.url ?? "/";
+        const method = req.method ?? "GET";
+        /* v8 ignore stop */
+        const pathname = new URL(requestUrl, "http://gateway.local").pathname;
+        if (method === "GET" && pathname === "/health") {
+            const body = JSON.stringify({
+                ok: true,
+                keys: keys.upstream.map((entry) => {
+                    const until = skipUntil(entry.label);
+                    return until ? { label: entry.label, available: false, skipUntil: until } : { label: entry.label, available: true };
+                }),
+            });
+            writeBuffered(res, { status: 200, headers: { "content-type": "application/json" }, body: Buffer.from(body) });
+            logRequest("-", method, pathname, 200, startedAt);
+            return;
+        }
+        if (!matchesMasterKey(presentedKey(req), masterDigest)) {
+            writeJsonError(res, 401, "authentication_error", "invalid x-api-key");
+            logRequest("-", method, pathname, 401, startedAt);
+            return;
+        }
+        const target = upstreamUrl(upstreamBase, requestUrl);
+        if (target.origin !== upstreamBase.origin) {
+            writeJsonError(res, 400, "invalid_request_error", "invalid request path");
+            logRequest("-", method, pathname, 400, startedAt);
+            return;
+        }
+        let body;
+        try {
+            body = await readRequestBody(req, maxRequestBytes);
+        }
+        catch (error) {
+            /* v8 ignore start -- the client went away while sending its body; there is no one to answer @preserve */
+            if (!(error instanceof RequestTooLargeError)) {
+                res.destroy();
+                return;
+            }
+            /* v8 ignore stop */
+            res.setHeader("connection", "close");
+            writeJsonError(res, 413, "request_too_large", `request body exceeds ${maxRequestBytes} bytes`);
+            logRequest("-", method, pathname, 413, startedAt);
+            return;
+        }
+        let lastCredit;
+        let lastCreditLabel = "-";
+        for (const entry of keys.upstream) {
+            if (skipUntil(entry.label))
+                continue;
+            let upstream;
+            try {
+                upstream = await sendUpstream(target, method, forwardedRequestHeaders(req, entry.key, body.length), body);
+            }
+            catch (error) {
+                (0, runtime_1.emitNervesEvent)({
+                    level: "error",
+                    component: "gateway",
+                    event: "gateway.upstream_error",
+                    message: "credit gateway could not reach the upstream API",
+                    meta: { label: entry.label, error: errorMessage(error) },
+                });
+                writeJsonError(res, 502, "api_error", "credit gateway could not reach the upstream API");
+                logRequest(entry.label, method, pathname, 502, startedAt);
+                return;
+            }
+            /* v8 ignore next -- Node always sets statusCode on an upstream response @preserve */
+            const status = upstream.response.statusCode ?? 502;
+            if (CREDIT_CHECK_STATUSES.has(status)) {
+                const buffered = {
+                    status,
+                    headers: responseHeaders(upstream.response.headers),
+                    body: await readAll(upstream.response),
+                };
+                if (isCreditExhaustedBody(buffered.body, upstream.response.headers["content-encoding"])) {
+                    markExhausted(entry);
+                    lastCredit = buffered;
+                    lastCreditLabel = entry.label;
+                    continue;
+                }
+                writeBuffered(res, buffered);
+                logRequest(entry.label, method, pathname, status, startedAt);
+                return;
+            }
+            res.writeHead(status, responseHeaders(upstream.response.headers));
+            res.flushHeaders();
+            (0, node_stream_1.pipeline)(upstream.response, res, (error) => {
+                if (error)
+                    upstream.request.destroy();
+                logRequest(entry.label, method, pathname, status, startedAt);
+            });
+            return;
+        }
+        if (lastCredit) {
+            writeBuffered(res, { ...lastCredit, status: 400 });
+        }
+        else {
+            writeJsonError(res, 400, "invalid_request_error", "Your credit balance is too low on every gateway key");
+        }
+        logRequest(lastCreditLabel, method, pathname, 400, startedAt);
+    }
+    const server = http.createServer((req, res) => {
+        handle(req, res).catch((error) => {
+            (0, runtime_1.emitNervesEvent)({
+                level: "error",
+                component: "gateway",
+                event: "gateway.request_error",
+                message: "credit gateway request failed",
+                meta: { error: errorMessage(error) },
+            });
+            /* v8 ignore next 4 -- failures after the headers went out are reported by the stream pipeline instead @preserve */
+            if (res.headersSent) {
+                res.destroy();
+                return;
+            }
+            writeJsonError(res, 502, "api_error", "credit gateway request failed");
+        });
+    });
+    await new Promise((resolve, reject) => {
+        server.once("error", reject);
+        /* v8 ignore next -- tests always bind port 0; the default is for production @preserve */
+        const port = options.port ?? exports.GATEWAY_DEFAULT_PORT;
+        server.listen(port, host, () => {
+            server.off("error", reject);
+            resolve();
+        });
+    });
+    const address = server.address();
+    const url = `http://${host}:${address.port}`;
+    (0, runtime_1.emitNervesEvent)({
+        component: "gateway",
+        event: "gateway.server_started",
+        message: "credit gateway started",
+        meta: { url, upstream: upstreamBase.origin, labels: keys.upstream.map((entry) => entry.label), statePath },
+    });
+    return {
+        server,
+        url,
+        port: address.port,
+        close: () => new Promise((resolve) => {
+            server.closeAllConnections();
+            server.close(() => {
+                (0, runtime_1.emitNervesEvent)({
+                    component: "gateway",
+                    event: "gateway.server_stopped",
+                    message: "credit gateway stopped",
+                    meta: { url },
+                });
+                resolve();
+            });
+        }),
+    };
+}
+/* v8 ignore start -- waits for real process signals; tests inject waitForStop @preserve */
+function waitForShutdownSignal() {
+    return new Promise((resolve) => {
+        process.once("SIGINT", () => resolve());
+        process.once("SIGTERM", () => resolve());
+    });
+}
+/* v8 ignore stop */
+/** Runs `ouro gateway serve` in the foreground until `waitForStop` resolves. */
+async function runCreditGatewayCommand(command, deps) {
+    const handle = await startCreditGateway(creditGatewayOptionsFromCli(command));
+    const message = `credit gateway listening on ${handle.url}\nhealth: ${handle.url}/health`;
+    deps.writeStdout(message);
+    /* v8 ignore next -- production waits for SIGINT/SIGTERM; tests inject waitForStop @preserve */
+    await (deps.waitForStop ?? waitForShutdownSignal)();
+    await handle.close();
+    return message;
+}