@antseed/cli 0.1.179 → 0.1.180

package/dist/gateway/server.js

@@ -1,13 +1,27 @@
+import { timingSafeEqual } from 'node:crypto';
 import * as http from 'node:http';
 import { DEFAULT_BUYER_IDENTITY } from '@antseed/node';
 import { SPEND_ATTRIBUTION_HEADER } from '../proxy/spend-attribution.js';
 import { BUYER_IDENTITY_HEADER } from '../proxy/request-utils.js';
+import { GATEWAY_CONTROL_HEADER, ROUTING_POLICY_HEADER, encodePolicyHeader, meaningfulPolicy, policyAllowsModel } from '../routing-policy/policy.js';
+import { effectiveKeyLimits, newRequestTag } from './accounting.js';
+import { errorMessage } from './errors.js';
 import { isClientCredentialHeader } from '../proxy/credential-headers.js';
-import { newRequestTag } from './accounting.js';
 import { parseBearerToken } from './keys.js';
-import { hasSpendLimits, LIMIT_PERIODS } from './limits.js';
+import { BUDGET_PERIODS } from './limits.js';
 import { formatUsdc, optionalUsdcToDecimalString, parseUsdToUsdc, usdcToDecimalString } from './money.js';
+import { OtlpExporter, observabilitySettings } from './observability.js';
+import { isEmptyPolicy, resolvePolicy } from './policy-resolver.js';
+import { END_USER_HEADER, applyPreset, effectiveRequestModel, extractEndUser, presetSlug } from './request-shaping.js';
+import { ResponseUsageReader } from './response-usage.js';
+import { SPEND_FEED_UNAUTHORIZED_HINT } from './spend-feed.js';
 import { PAYMENT_REQUIRED_HEADER, PAYMENT_RESPONSE_HEADER, PAYMENT_SIGNATURE_HEADER, X402_VERSION, buildPaymentRequirements, checkPaymentPayload, decodeHeaderJson, encodeHeaderJson, } from './x402.js';
+/**
+ * The gateway's own components (the console chat agent) call `/v1` as a key
+ * by its id, without its secret: this header plus the control secret, from
+ * loopback only. Stripped from everything forwarded to the buyer.
+ */
+export const GATEWAY_INTERNAL_KEY_HEADER = 'x-antseed-gateway-key';
 const HOP_BY_HOP = new Set([
     'connection',
     'keep-alive',
@@ -22,6 +36,19 @@ const HOP_BY_HOP = new Set([
 const MAX_MODEL_SNIFF_BYTES = 4 * 1024 * 1024;
 /** Largest request body the gateway accepts, matching the buyer's default upload limit. */
 const MAX_BODY_BYTES = 64 * 1024 * 1024;
+/** How much of a failed response is read for its error code and message. */
+const MAX_ERROR_BODY_BYTES = 16 * 1024;
+const MAX_ERROR_MESSAGE_CHARS = 500;
+/** Request and response bodies kept per request while content logging is on. */
+const MAX_LOGGED_CONTENT_BYTES = 64 * 1024;
+const RETENTION_SWEEP_MS = 60 * 60 * 1000;
+const DAY_MS = 24 * 60 * 60 * 1000;
+/** Why a key with caps cannot be served while its buyer's spend feed is not reporting. */
+const SPEND_FEED_UNAVAILABLE_MESSAGES = {
+    unsupported: 'The buyer for this API key does not report spend; upgrade it to enforce spend limits',
+    unauthorized: `The buyer for this API key does not report spend to this gateway; ${SPEND_FEED_UNAUTHORIZED_HINT}`,
+    unreachable: 'The buyer for this API key is not reachable',
+};
 const KEY_INFO_PATH = '/v1/key';
 const TOPUP_PATH = '/v1/key/topup';
 /**
@@ -48,8 +75,12 @@ export class GatewayServer {
     _options;
     _server = null;
     _port = 0;
+    _retentionTimer = null;
+    _pruning = null;
+    _exporter;
     constructor(_options) {
         this._options = _options;
+        this._exporter = _options.exporter ?? new OtlpExporter(() => observabilitySettings(_options.store), { onLog: (m) => this._log(m) });
     }
     get port() {
         return this._port;
@@ -59,7 +90,7 @@ export class GatewayServer {
             return this._port;
         this._server = http.createServer((req, res) => {
             this._handle(req, res).catch((error) => {
-                this._log(`gateway error: ${error instanceof Error ? error.message : String(error)}`);
+                this._log(`gateway error: ${errorMessage(error)}`);
                 if (!res.headersSent)
                     sendError(res, 500, 'api_error', 'internal_error', 'Gateway error');
                 else
@@ -71,12 +102,42 @@ export class GatewayServer {
             this._server.listen(this._options.listenPort ?? 0, this._options.listenHost ?? '127.0.0.1', () => resolve());
         });
         this._port = this._server.address().port;
+        void this.pruneRequestLog();
+        this._retentionTimer = setInterval(() => { void this.pruneRequestLog(); }, RETENTION_SWEEP_MS);
+        this._retentionTimer.unref?.();
         return this._port;
     }
+    /**
+     * Applies the request-log retention setting; resolves to rows removed. A
+     * large backlog is pruned one chunk per event-loop turn, and a sweep that
+     * is still running is joined rather than started twice.
+     */
+    pruneRequestLog(now = Date.now()) {
+        if (this._pruning)
+            return this._pruning;
+        const { retentionDays } = observabilitySettings(this._options.store);
+        if (!retentionDays)
+            return Promise.resolve(0);
+        this._pruning = this._options.store.pruneRequests(now - retentionDays * DAY_MS)
+            .then((removed) => {
+            if (removed > 0)
+                this._log(`pruned ${removed} request log row(s) older than ${retentionDays} day(s)`);
+            return removed;
+        }, (error) => {
+            this._log(`gateway could not prune the request log: ${errorMessage(error)}`);
+            return 0;
+        })
+            .finally(() => { this._pruning = null; });
+        return this._pruning;
+    }
     async stop() {
         const server = this._server;
         this._server = null;
         this._port = 0;
+        if (this._retentionTimer)
+            clearInterval(this._retentionTimer);
+        this._retentionTimer = null;
+        await this._exporter.stop();
         if (!server)
             return;
         await new Promise((resolve) => server.close(() => resolve()));
@@ -87,26 +148,21 @@ export class GatewayServer {
     async _handle(req, res) {
         const method = req.method ?? 'GET';
         const path = req.url ?? '/';
+        const pathname = path.split('?')[0];
+        if (this._options.console && (pathname === '/console' || pathname.startsWith('/console/'))) {
+            if (await this._options.console.handle(req, res))
+                return;
+        }
         const route = canonicalizeRoute(method, path);
         if (!route) {
             this._log(`gateway rejected route: ${method} ${path}`);
             sendError(res, 404, 'invalid_request_error', 'not_found', 'Not found');
             return;
         }
-        const canonicalPath = route.path;
-        const secret = parseBearerToken(req.headers.authorization);
-        const key = secret ? this._options.store.findKeyBySecret(secret) : null;
-        if (!key || key.status !== 'active') {
-            this._log(`gateway rejected authentication: ${method} ${path}`);
-            res.setHeader('www-authenticate', 'Bearer');
-            sendError(res, 401, 'authentication_error', key ? 'key_revoked' : 'invalid_api_key', key ? 'API key has been revoked' : 'Invalid API key');
+        const authenticated = this._authenticate(req, res, `${method} ${path}`);
+        if (!authenticated)
             return;
-        }
-        if (key.expiresAt !== null && key.expiresAt <= Date.now()) {
-            res.setHeader('www-authenticate', 'Bearer');
-            sendError(res, 401, 'authentication_error', 'key_expired', 'API key has expired');
-            return;
-        }
+        const { key, context } = authenticated;
         if (route.local) {
             if (route.prefix === TOPUP_PATH)
                 await this._topup(req, res, key);
@@ -114,112 +170,324 @@ export class GatewayServer {
                 sendJson(res, 200, { data: await this._keyInfo(key) });
             return;
         }
-        const buyerPort = this._options.buyerPort;
         // Caps are only as good as the spend that reaches the ledger, so a key
         // with caps fails closed while its buyer is not reporting spend.
-        if (route.paid && hasSpendLimits(key.limits) && this._options.spendFeedState() !== 'reporting') {
-            await this._options.refreshSpendFeed();
-            const state = this._options.spendFeedState();
-            if (state !== 'reporting') {
-                sendError(res, 503, 'api_error', 'spend_tracking_unavailable', state === 'unsupported'
-                    ? 'The buyer for this API key does not report spend; upgrade it to enforce spend limits'
-                    : 'The buyer for this API key is not reachable');
-                return;
-            }
-        }
-        const body = await readBody(req);
+        if (route.paid && this._options.accounting.hasBudgets(key, context) && !await this._spendFeedReporting(res))
+            return;
+        let body = await readBody(req);
         if (!body)
             return sendBodyTooLarge(res);
-        let tag;
-        if (route.paid) {
-            const admission = this._options.accounting.admit(key);
-            if (!admission.ok) {
-                this._log(`gateway spend limit reached: key=${key.id} period=${admission.breach.period}`);
-                sendJson(res, 402, { error: spendLimitError(admission.breach) });
+        const contentType = req.headers['content-type'];
+        let parsed = parseJsonBody(body, contentType);
+        // What the buyer routes by (`service ?? model`), so the allow list and
+        // the request log see the model that is actually bought.
+        let model = effectiveRequestModel(parsed, body, contentType);
+        // `model: "@preset/<slug>"` runs the workspace's (or org's) preset.
+        const slug = presetSlug(model);
+        const preset = slug ? this._options.store.findPresetBySlug(slug, key.workspaceId) : null;
+        if (slug) {
+            if (!parsed) {
+                sendError(res, 400, 'invalid_request_error', 'preset_requires_json', 'Presets can only be used with JSON request bodies');
                 return;
             }
-            tag = admission.tag;
-        }
-        else {
-            tag = newRequestTag();
+            if (!preset) {
+                sendError(res, 400, 'invalid_request_error', 'preset_not_found', `No preset named "${slug}"`);
+                return;
+            }
+            parsed = applyPreset(parsed, preset, route.prefix);
+            body = Buffer.from(JSON.stringify(parsed), 'utf8');
+            model = preset.model;
         }
-        this._options.store.startRequest({
+        const policy = this._routingPolicy(res, route, key, context, preset, model);
+        if (!policy.allowed)
+            return;
+        const tag = this._admit(res, route, key, context);
+        if (!tag)
+            return;
+        const request = {
             tag,
-            keyId: key.id,
-            buyerIdentity: key.buyerIdentity,
+            key,
             method,
-            path: canonicalPath.split('?')[0],
-            model: sniffModel(body, req.headers['content-type']),
+            path,
+            buyerPath: route.path,
+            requestPath: route.prefix,
+            model: model ? model.slice(0, 200) : null,
+            endUser: extractEndUser(parsed, firstHeader(req.headers[END_USER_HEADER]) || undefined),
             startedAt: Date.now(),
-        });
-        this._options.store.touchKey(key.id);
-        this._log(`gateway request: key=${key.id} identity=${key.buyerIdentity} ${method} ${path} -> ${canonicalPath}`);
-        let finished = false;
-        const finish = (status, buyerRequestId) => {
-            if (finished)
-                return;
-            finished = true;
-            this._options.store.finishRequest(tag, { status, buyerRequestId });
-            this._options.accounting.finish(tag);
+            body,
+            policyHeaders: policy.headers,
+            modelListPolicy: route.prefix === '/v1/models' && policy.policy.allowedModels ? policy.policy : null,
         };
-        const headers = {};
-        for (const [name, value] of Object.entries(req.headers)) {
-            const normalized = name.toLowerCase();
-            // The client's key authenticated it to this gateway; its other
-            // credentials are never needed downstream (see credential-headers.ts).
-            if (normalized === 'host' || isClientCredentialHeader(normalized))
-                continue;
-            // The key decides who pays and how spend is tagged, never the client.
-            if (normalized === 'content-length' || normalized === SPEND_ATTRIBUTION_HEADER || normalized === BUYER_IDENTITY_HEADER)
-                continue;
-            if (normalized.startsWith('x-forwarded-') || HOP_BY_HOP.has(normalized))
-                continue;
-            headers[name] = value;
+        try {
+            this._options.store.startRequest({
+                tag,
+                keyId: key.id,
+                buyerIdentity: key.buyerIdentity,
+                method,
+                path: request.requestPath,
+                model: request.model,
+                startedAt: request.startedAt,
+                workspaceId: key.workspaceId,
+                memberId: key.ownerMemberId,
+                endUser: request.endUser,
+            });
+            this._options.store.touchKey(key.id);
         }
-        headers.host = `127.0.0.1:${buyerPort}`;
-        headers.connection = 'close';
-        headers['content-length'] = String(body.length);
-        headers['x-antseed-system-proxy-source'] = tunnelRequestSource(req.headers);
-        headers[SPEND_ATTRIBUTION_HEADER] = tag;
-        if (key.buyerIdentity !== DEFAULT_BUYER_IDENTITY)
-            headers[BUYER_IDENTITY_HEADER] = key.buyerIdentity;
-        const upstream = http.request({
-            hostname: '127.0.0.1',
-            port: buyerPort,
-            method,
-            path: canonicalPath,
-            headers,
-        }, (upstreamRes) => {
-            const status = upstreamRes.statusCode ?? 502;
-            const buyerRequestId = firstHeader(upstreamRes.headers['x-antseed-request-id']) || null;
-            const responseHeaders = {};
-            for (const [name, value] of Object.entries(upstreamRes.headers)) {
-                if (!HOP_BY_HOP.has(name.toLowerCase()) && value !== undefined)
-                    responseHeaders[name] = value;
-            }
-            responseHeaders.connection = 'close';
-            res.writeHead(status, responseHeaders);
-            upstreamRes.pipe(res);
-            upstreamRes.once('end', () => finish(status, buyerRequestId));
-            upstreamRes.once('error', () => finish(status, buyerRequestId));
-            res.once('close', () => finish(status, buyerRequestId));
-        });
-        upstream.on('error', (error) => {
-            this._log(`gateway upstream error: ${error.message}`);
-            finish(502, null);
-            if (!res.headersSent) {
-                sendError(res, 502, 'api_error', 'buyer_unavailable', 'Antseed buyer proxy is unavailable');
+        catch (error) {
+            // Nothing was sent; the hold must not keep counting against the caps.
+            this._options.accounting.release(tag);
+            throw error;
+        }
+        this._forward(req, res, request);
+    }
+    /** The request's active API key and who it is accounted to; answers 401 itself otherwise. */
+    _authenticate(req, res, requestLine) {
+        const store = this._options.store;
+        const key = this._requestKey(req);
+        if (!key || key.status !== 'active') {
+            this._log(`gateway rejected authentication: ${requestLine}`);
+            if (key)
+                sendUnauthorized(res, 'key_revoked', 'API key has been revoked');
+            else
+                sendUnauthorized(res, 'invalid_api_key', 'Invalid API key');
+            return null;
+        }
+        if (key.expiresAt !== null && key.expiresAt <= Date.now()) {
+            sendUnauthorized(res, 'key_expired', 'API key has expired');
+            return null;
+        }
+        // Loaded once and shared by policy resolution and budget admission.
+        const member = key.ownerMemberId ? store.getMember(key.ownerMemberId) : null;
+        if (member?.status === 'disabled') {
+            sendUnauthorized(res, 'key_revoked', 'API key has been revoked');
+            return null;
+        }
+        return { key, context: { member, workspace: store.getWorkspace(key.workspaceId) } };
+    }
+    /**
+     * The key a request names: by id for the gateway's own components (see
+     * GATEWAY_INTERNAL_KEY_HEADER), else by its Bearer secret. The id header is
+     * only honored from an internal caller; from anyone else it is ignored, so
+     * it can neither stand in for a key nor block a valid Bearer one.
+     */
+    _requestKey(req) {
+        const internalKeyId = firstHeader(req.headers[GATEWAY_INTERNAL_KEY_HEADER]);
+        if (internalKeyId && this._internalCaller(req))
+            return this._options.store.getKey(internalKeyId);
+        const secret = parseBearerToken(req.headers.authorization);
+        return secret ? this._options.store.findKeyBySecret(secret) : null;
+    }
+    /** A request from the gateway process itself: loopback, carrying the control secret. */
+    _internalCaller(req) {
+        const expected = this._options.controlSecret;
+        const sent = firstHeader(req.headers[GATEWAY_CONTROL_HEADER]);
+        if (!expected || !sent || !isLoopback(req.socket.remoteAddress))
+            return false;
+        const a = Buffer.from(sent);
+        const b = Buffer.from(expected);
+        return a.length === b.length && timingSafeEqual(a, b);
+    }
+    /** Whether the buyer reports spend, refreshing the feed once; answers 503 itself when it does not. */
+    async _spendFeedReporting(res) {
+        if (this._options.spendFeedState() === 'reporting')
+            return true;
+        await this._options.refreshSpendFeed();
+        const state = this._options.spendFeedState();
+        if (state === 'reporting')
+            return true;
+        sendError(res, 503, 'api_error', 'spend_tracking_unavailable', SPEND_FEED_UNAVAILABLE_MESSAGES[state]);
+        return false;
+    }
+    /**
+     * The key's effective routing policy: refuses (answering itself) a model
+     * it does not allow, or a seller restriction the buyer would not apply.
+     * Settings that change nothing (the default sort, flags set to false) are
+     * not sent: a request without restrictions reaches the buyer exactly like
+     * one through a gateway without policies.
+     */
+    _routingPolicy(res, route, key, context, preset, model) {
+        const { policy } = resolvePolicy(this._options.store, { key, preset, member: context.member, workspace: context.workspace });
+        if ((route.paid || model) && !policyAllowsModel(policy, model)) {
+            sendError(res, 403, 'permission_error', 'model_not_allowed', model
+                ? `Model "${model}" is not allowed for this API key`
+                : 'This API key may only use specific models; name one in the request');
+            return { allowed: false };
+        }
+        const routed = meaningfulPolicy(policy);
+        if (isEmptyPolicy(routed))
+            return { allowed: true, headers: {}, policy };
+        const controlSecret = this._options.controlSecret ?? null;
+        const sellersRestricted = restrictsSellers(routed);
+        if (!controlSecret && sellersRestricted) {
+            sendError(res, 503, 'api_error', 'routing_policy_unavailable', 'This API key has a routing policy the gateway cannot pass to the buyer');
+            return { allowed: false };
+        }
+        if (route.paid && sellersRestricted && this._options.buyerPolicyUnsupported?.()) {
+            sendError(res, 503, 'api_error', 'buyer_policy_unsupported', "The buyer does not apply this API key's routing policy; upgrade it or check the gateway control secret");
+            return { allowed: false };
+        }
+        if (!controlSecret)
+            return { allowed: true, headers: {}, policy };
+        return { allowed: true, headers: { [ROUTING_POLICY_HEADER]: encodePolicyHeader(routed), [GATEWAY_CONTROL_HEADER]: controlSecret }, policy };
+    }
+    /** The request's tag; a paid request is admitted against its budgets first (402 answered here when one is spent). */
+    _admit(res, route, key, context) {
+        if (!route.paid)
+            return newRequestTag();
+        const admission = this._options.accounting.admit(key, context);
+        if (admission.ok)
+            return admission.tag;
+        this._log(`gateway spend limit reached: key=${key.id} level=${admission.breach.level ?? 'key'} period=${admission.breach.period}`);
+        sendJson(res, 402, { error: spendLimitError(admission.breach) });
+        return null;
+    }
+    /**
+     * Sends an admitted request to the buyer and streams the answer back.
+     * Every path must finish the request (and so release or start expiring
+     * its hold); an unexpected throw must not leak it.
+     */
+    _forward(req, res, request) {
+        const { tag, key, method, startedAt, endUser, body } = request;
+        const buyerPort = this._options.buyerPort;
+        let finish = null;
+        let sentToBuyer = false;
+        try {
+            this._log(`gateway request: key=${key.id} identity=${key.buyerIdentity} ${method} ${request.path} -> ${request.buyerPath}`);
+            const observability = observabilitySettings(this._options.store);
+            const requestContent = observability.logContent ? truncateContent(body) : null;
+            let responseChunks = [];
+            // The start of a failed response, read whatever the content setting, for its error code and message.
+            let errorChunks = [];
+            let gatewayError = null;
+            let sellerPeerId = null;
+            let reportedLatency = null;
+            let servedFree = false;
+            // Token counts the response reports, kept on the request until (or if
+            // the buyer never reports) its spend.
+            let usageReader = null;
+            let finished = false;
+            finish = (status, buyerRequestId) => {
+                if (finished)
+                    return;
+                finished = true;
+                const finishedAt = Date.now();
+                const latencyMs = reportedLatency ?? finishedAt - startedAt;
+                const responseContent = observability.logContent ? truncateContent(Buffer.concat(responseChunks)) : null;
+                const store = this._options.store;
+                try {
+                    const error = status >= 400 ? gatewayError ?? parseErrorBody(Buffer.concat(errorChunks), status) : null;
+                    store.finishRequest(tag, { status, buyerRequestId, error });
+                    store.recordRequestOutcome(tag, { sellerPeerId, latencyMs, endUser, servedFree });
+                    const usage = usageReader?.result() ?? null;
+                    if (usage)
+                        store.recordResponseUsage(tag, usage);
+                    if (observability.logContent)
+                        store.recordRequestContent(tag, { requestBody: requestContent, responseBody: responseContent });
+                }
+                catch (error) {
+                    this._log(`gateway could not record request ${tag}: ${errorMessage(error)}`);
+                }
+                this._options.accounting.finish(tag);
+                this._exporter.record({
+                    tag, method, path: request.requestPath, model: request.model, status, startedAt, finishedAt,
+                    keyId: key.id, workspaceId: key.workspaceId, memberId: key.ownerMemberId, endUser, sellerPeerId, latencyMs,
+                    ...(observability.logContent ? { requestBody: requestContent, responseBody: responseContent } : {}),
+                });
+            };
+            const headers = { ...forwardedHeaders(req.headers), ...request.policyHeaders };
+            headers.host = `127.0.0.1:${buyerPort}`;
+            headers.connection = 'close';
+            headers['content-length'] = String(body.length);
+            headers['x-antseed-system-proxy-source'] = tunnelRequestSource(req.headers);
+            headers[SPEND_ATTRIBUTION_HEADER] = tag;
+            if (key.buyerIdentity !== DEFAULT_BUYER_IDENTITY) {
+                headers[BUYER_IDENTITY_HEADER] = key.buyerIdentity;
+                // The buyer lets only its gateway pay from a non-default wallet.
+                const controlSecret = this._options.controlSecret;
+                if (controlSecret)
+                    headers[GATEWAY_CONTROL_HEADER] = controlSecret;
             }
+            const upstream = http.request({
+                hostname: '127.0.0.1',
+                port: buyerPort,
+                method,
+                path: request.buyerPath,
+                headers,
+            }, (upstreamRes) => {
+                const status = upstreamRes.statusCode ?? 502;
+                const buyerRequestId = firstHeader(upstreamRes.headers['x-antseed-request-id']) || null;
+                sellerPeerId = firstHeader(upstreamRes.headers['x-antseed-peer-id']).slice(0, 200) || null;
+                reportedLatency = latencyHeader(firstHeader(upstreamRes.headers['x-antseed-latency-ms']));
+                servedFree = freeSellerPricing(upstreamRes.headers);
+                if (observability.logContent)
+                    responseChunks = collectPrefix(upstreamRes, MAX_LOGGED_CONTENT_BYTES);
+                if (status >= 400)
+                    errorChunks = collectPrefix(upstreamRes, MAX_ERROR_BODY_BYTES);
+                else if (request.model !== null)
+                    usageReader = readUsage(upstreamRes, (message) => this._log(message));
+                const responseHeaders = {};
+                for (const [name, value] of Object.entries(upstreamRes.headers)) {
+                    if (!HOP_BY_HOP.has(name.toLowerCase()) && value !== undefined)
+                        responseHeaders[name] = value;
+                }
+                responseHeaders.connection = 'close';
+                upstreamRes.once('error', () => finish(status, buyerRequestId));
+                res.once('close', () => finish(status, buyerRequestId));
+                const modelListPolicy = request.modelListPolicy;
+                if (modelListPolicy && status === 200) {
+                    const chunks = [];
+                    upstreamRes.on('data', (chunk) => chunks.push(chunk));
+                    upstreamRes.once('end', () => {
+                        const listing = filterModelList(Buffer.concat(chunks), modelListPolicy);
+                        res.writeHead(status, { ...responseHeaders, 'content-length': String(listing.length) });
+                        res.end(listing);
+                        finish(status, buyerRequestId);
+                    });
+                    return;
+                }
+                res.writeHead(status, responseHeaders);
+                upstreamRes.pipe(res);
+                upstreamRes.once('end', () => finish(status, buyerRequestId));
+            });
+            upstream.on('error', (error) => {
+                this._log(`gateway upstream error: ${error.message}`);
+                gatewayError = { code: 'buyer_unavailable', message: 'Antseed buyer proxy is unavailable' };
+                finish(502, null);
+                if (!res.headersSent) {
+                    sendError(res, 502, 'api_error', 'buyer_unavailable', 'Antseed buyer proxy is unavailable');
+                }
+                else {
+                    res.destroy();
+                }
+            });
+            // A client that disconnects mid-stream should stop the paid request too.
+            res.once('close', () => {
+                if (!res.writableFinished)
+                    upstream.destroy();
+            });
+            sentToBuyer = true;
+            upstream.end(body);
+        }
+        catch (error) {
+            this._log(`gateway error after admission: ${errorMessage(error)}`);
+            if (finish)
+                finish(500, null);
             else {
-                res.destroy();
+                try {
+                    this._options.store.finishRequest(tag, { status: 500, buyerRequestId: null, error: { code: 'internal_error', message: 'Gateway error' } });
+                }
+                catch {
+                    // Already logged above; the hold still goes.
+                }
             }
-        });
-        // A client that disconnects mid-stream should stop the paid request too.
-        res.once('close', () => {
-            if (!res.writableFinished)
-                upstream.destroy();
-        });
-        upstream.end(body);
+            // A request the buyer never saw cannot be signed for: drop its hold now.
+            if (!sentToBuyer)
+                this._options.accounting.release(tag);
+            if (!res.headersSent)
+                sendError(res, 500, 'api_error', 'internal_error', 'Gateway error');
+            else
+                res.destroy();
+        }
     }
     /**
      * x402 top-up: the key holder pays USDC straight to the key's buyer wallet.
@@ -311,7 +579,7 @@ export class GatewayServer {
             });
         }
         catch (error) {
-            this._log(`gateway top-up settled but NOT recorded in the ledger: key=${key.id} amount=${formatUsdc(amountUsdc)} tx=${settled.transaction}: ${error instanceof Error ? error.message : String(error)}`);
+            this._log(`gateway top-up settled but NOT recorded in the ledger: key=${key.id} amount=${formatUsdc(amountUsdc)} tx=${settled.transaction}: ${errorMessage(error)}`);
         }
         this._log(`gateway top-up: key=${key.id} identity=${key.buyerIdentity} amount=${formatUsdc(amountUsdc)} tx=${settled.transaction}`);
         res.setHeader(PAYMENT_RESPONSE_HEADER, encodeHeaderJson(settled));
@@ -338,16 +606,18 @@ export class GatewayServer {
             return await topup.facilitator.settle(payment, requirements);
         }
         catch (error) {
-            this._log(`gateway facilitator error: ${error instanceof Error ? error.message : String(error)}`);
+            this._log(`gateway facilitator error: ${errorMessage(error)}`);
             return failure('unexpected_settle_error');
         }
     }
     async _keyInfo(key) {
-        const spent = this._options.store.periodSpend(key.id);
+        const spent = this._options.store.spendByPeriod({ keyId: key.id });
         const usage = this._options.store.usageStats(key.id);
         const buyerAddress = await this._options.identityAddress(key.buyerIdentity).catch(() => null);
-        const limits = Object.fromEntries(LIMIT_PERIODS.map((period) => {
-            const limit = key.limits[period];
+        // The caps admission enforces: the lower of the admins' and the owner's.
+        const caps = effectiveKeyLimits(key);
+        const limits = Object.fromEntries(BUDGET_PERIODS.map((period) => {
+            const limit = caps[period];
             return [period, {
                     limit_usd: optionalUsdcToDecimalString(limit),
                     spent_usd: usdcToDecimalString(spent[period]),
@@ -381,11 +651,13 @@ export class GatewayServer {
  */
 function spendLimitError(breach) {
     const label = breach.period === 'total' ? 'lifetime' : breach.period;
+    const level = breach.level ?? 'key';
     return {
         type: 'insufficient_quota',
         code: 'spend_limit_reached',
-        message: `This API key reached its ${label} spend limit of ${formatUsdc(breach.limitUsdc)}.`,
+        message: `${budgetHolder(level)} reached its ${label} spend limit of ${formatUsdc(breach.limitUsdc)}.`,
         limit: {
+            level,
             period: breach.period,
             limit_usd: usdcToDecimalString(breach.limitUsdc),
             spent_usd: usdcToDecimalString(breach.spentUsdc),
@@ -393,6 +665,13 @@ function spendLimitError(breach) {
         },
     };
 }
+function budgetHolder(level) {
+    if (level === 'key')
+        return 'This API key';
+    if (level === 'member')
+        return 'The member who owns this API key';
+    return 'This API key\'s workspace';
+}
 function sendJson(res, status, payload) {
     res.writeHead(status, { 'content-type': 'application/json' });
     res.end(JSON.stringify(payload));
@@ -400,6 +679,10 @@ function sendJson(res, status, payload) {
 function sendError(res, status, type, code, message) {
     sendJson(res, status, { error: { message, type, code } });
 }
+function sendUnauthorized(res, code, message) {
+    res.setHeader('www-authenticate', 'Bearer');
+    sendError(res, 401, 'authentication_error', code, message);
+}
 /** The request body, or null once it exceeds MAX_BODY_BYTES (the rest is drained, not kept). */
 async function readBody(req) {
     if (Number(req.headers['content-length']) > MAX_BODY_BYTES) {
@@ -418,19 +701,132 @@ async function readBody(req) {
 function sendBodyTooLarge(res) {
     sendError(res, 413, 'invalid_request_error', 'request_too_large', `Request bodies are limited to ${MAX_BODY_BYTES / 1024 / 1024} MiB`);
 }
-function sniffModel(body, contentType) {
+/** A JSON object body, or null (empty, too large to inspect, not JSON, not an object). */
+function parseJsonBody(body, contentType) {
     if (body.length === 0 || body.length > MAX_MODEL_SNIFF_BYTES)
         return null;
     if (contentType && !contentType.includes('json'))
         return null;
     try {
-        const parsed = JSON.parse(body.toString('utf8'));
-        return typeof parsed.model === 'string' ? parsed.model.slice(0, 200) : null;
+        return jsonObject(JSON.parse(body.toString('utf8')));
     }
     catch {
         return null;
     }
 }
+function jsonObject(value) {
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : null;
+}
+/**
+ * Error code and message of a failed response: the OpenAI/Anthropic envelope
+ * (`{ error: { code | type, message } }`, `{ error: "…" }`), a top-level
+ * `{ code, message }`, or the start of a non-JSON body.
+ */
+export function parseErrorBody(body, status) {
+    const text = body.subarray(0, MAX_ERROR_BODY_BYTES).toString('utf8').trim();
+    const fallback = `http_${status}`;
+    const clip = (value) => value ? value.slice(0, MAX_ERROR_MESSAGE_CHARS) : null;
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return { code: fallback, message: clip(text.replace(/\s+/g, ' ')) };
+    }
+    const pick = (value) => typeof value === 'string' && value.trim() ? value.trim() : null;
+    const root = jsonObject(parsed) ?? {};
+    const envelope = root['error'];
+    if (typeof envelope === 'string')
+        return { code: pick(root['code']) ?? fallback, message: clip(envelope) };
+    const inner = jsonObject(envelope) ?? root;
+    return {
+        code: (pick(inner['code']) ?? pick(inner['type']) ?? fallback).slice(0, 100),
+        message: clip(pick(inner['message']) ?? pick(root['message']) ?? pick(root['detail'])),
+    };
+}
+/** Keeps the first `maxBytes` (or so) of a stream as it flows past. */
+function collectPrefix(stream, maxBytes) {
+    const chunks = [];
+    let bytes = 0;
+    stream.on('data', (chunk) => {
+        if (bytes >= maxBytes)
+            return;
+        chunks.push(chunk);
+        bytes += chunk.length;
+    });
+    return chunks;
+}
+/** Feeds a successful model response to a usage reader as it streams; a reader error only stops reading. */
+function readUsage(stream, log) {
+    const reader = new ResponseUsageReader(firstHeader(stream.headers['content-type']));
+    const onData = (chunk) => {
+        try {
+            reader.push(chunk);
+        }
+        catch (error) {
+            stream.off('data', onData);
+            log(`gateway could not read response usage: ${errorMessage(error)}`);
+        }
+    };
+    stream.on('data', onData);
+    return reader;
+}
+/** The buyer's own latency measurement, when it sent a usable one. */
+/**
+ * Whether the seller's advertised prices (the buyer's pricing headers) are
+ * all zero: a free seller, for which the buyer never reports spend. Unknown
+ * input or output prices are not free.
+ */
+function freeSellerPricing(headers) {
+    const price = (name) => {
+        const value = firstHeader(headers[name]);
+        const amount = Number(value);
+        return value && Number.isFinite(amount) ? amount : null;
+    };
+    const cached = price('x-antseed-cached-input-usd-per-million');
+    return price('x-antseed-input-usd-per-million') === 0 && price('x-antseed-output-usd-per-million') === 0 && (cached === null || cached === 0);
+}
+function latencyHeader(value) {
+    const latency = Number(value);
+    return value && Number.isFinite(latency) && latency >= 0 ? Math.floor(latency) : null;
+}
+/**
+ * Client headers never forwarded: the gateway sets its own `host` and
+ * `content-length`, and the key (never the client) decides who pays, how
+ * spend is tagged and which sellers may serve.
+ */
+const STRIPPED_HEADERS = new Set([
+    'host',
+    'content-length',
+    SPEND_ATTRIBUTION_HEADER,
+    BUYER_IDENTITY_HEADER,
+    ROUTING_POLICY_HEADER,
+    GATEWAY_CONTROL_HEADER,
+    GATEWAY_INTERNAL_KEY_HEADER,
+    END_USER_HEADER,
+]);
+/** Client headers passed on to the buyer, minus everything the key (not the client) decides. */
+function forwardedHeaders(incoming) {
+    const headers = {};
+    for (const [name, value] of Object.entries(incoming)) {
+        const normalized = name.toLowerCase();
+        // The client's key authenticated it to this gateway; its other
+        // credentials are never needed downstream (see credential-headers.ts).
+        if (isClientCredentialHeader(normalized) || STRIPPED_HEADERS.has(normalized))
+            continue;
+        if (normalized.startsWith('x-forwarded-') || HOP_BY_HOP.has(normalized))
+            continue;
+        headers[name] = value;
+    }
+    return headers;
+}
+function truncateContent(body) {
+    return body.subarray(0, MAX_LOGGED_CONTENT_BYTES).toString('utf8');
+}
+/** Whether a policy says anything the buyer must apply (the gateway enforces `allowedModels` itself). */
+function restrictsSellers(policy) {
+    return Object.keys(policy).some((field) => field !== 'allowedModels' && field !== 'sort' && field !== 'preferFreePeers');
+}
 function tunnelRequestSource(headers) {
     const originator = normalizeSource(firstHeader(headers.originator));
     if (originator)
@@ -442,12 +838,32 @@ function tunnelRequestSource(headers) {
     const product = normalizeSource(userAgent.split(/[/\s]/, 1)[0] ?? '');
     return product.startsWith('cursor') ? 'cursor' : 'public-tunnel';
 }
+function isLoopback(address) {
+    return address === '127.0.0.1' || address === '::1' || address === '::ffff:127.0.0.1';
+}
 function firstHeader(value) {
     return Array.isArray(value) ? value[0] ?? '' : value ?? '';
 }
 function normalizeSource(value) {
     return value.trim().toLowerCase().replace(/[^a-z0-9.]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 64);
 }
+/** A `/v1/models` listing without the models the policy does not allow (matched by id or alias). */
+function filterModelList(body, policy) {
+    let listing;
+    try {
+        listing = JSON.parse(body.toString('utf8'));
+    }
+    catch {
+        return body;
+    }
+    if (!listing || !Array.isArray(listing.data))
+        return body;
+    listing.data = listing.data.filter((entry) => {
+        const names = [entry?.id, ...(Array.isArray(entry?.aliases) ? entry.aliases : [])];
+        return names.some((name) => typeof name === 'string' && policyAllowsModel(policy, name));
+    });
+    return Buffer.from(JSON.stringify(listing), 'utf8');
+}
 function canonicalizeRoute(method, path) {
     const queryIndex = path.indexOf('?');
     const pathname = (queryIndex === -1 ? path : path.slice(0, queryIndex)).toLowerCase();