threadwire 0.1.6 → 0.1.9

package/src/kimi-model-broker-policy.js

@@ -0,0 +1,209 @@
+// @ts-check
+
+import {randomBytes} from "node:crypto"
+
+const TOKEN_PATTERN = /^[A-Za-z0-9_-]{32,128}$/u
+const ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$/u
+const MODEL_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$/u
+const ALIAS_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/u
+const TASK_PATTERN = /^[0-9a-f]{64}$/u
+const SESSION_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,511}$/u
+
+/** @typedef {{provider: "kimi", runId: string, networkId: string, taskId: string, sessionId: string, modelAlias: string, model: string, expiresAt: number, active: boolean}} KimiGrant */
+/** @typedef {{alias: string, model: string, protocol: "kimi"}} ApprovedKimiModel */
+const ALLOWED_HEADERS = new Set([
+  "authorization", "content-length", "content-type", "accept", "accept-encoding",
+  "accept-language", "sec-fetch-mode", "user-agent",
+  "x-stainless-arch", "x-stainless-lang", "x-stainless-os",
+  "x-stainless-package-version", "x-stainless-runtime", "x-stainless-runtime-version",
+  "x-stainless-retry-count", "x-stainless-timeout", "x-stainless-async"
+])
+const BODY_KEYS = new Set([
+  "model", "messages", "stream", "stream_options", "tools", "thinking",
+  "max_completion_tokens", "temperature", "top_p", "n", "presence_penalty",
+  "frequency_penalty", "stop", "prompt_cache_key", "response_format"
+])
+const NUMERIC_KEYS = new Set([
+  "max_completion_tokens", "temperature", "top_p", "n", "presence_penalty", "frequency_penalty"
+])
+
+export const KIMI_CHAT_COMPLETIONS_PATH = "/coding/v1/chat/completions"
+
+/** @param {{now?: () => number, random?: (bytes: number) => Buffer}} [options] */
+export function createKimiGrantStore(options = {}) {
+  const now = options.now ?? Date.now
+  const random = options.random ?? randomBytes
+  /** @type {Map<string, KimiGrant>} */
+  const grants = new Map()
+  return {
+    /** @param {{provider: "kimi", runId: string, networkId: string, taskId: string, sessionId: string, modelAlias: string, model: string, ttlMs: number}} grant */
+    issue(grant) {
+      if (grant.provider !== "kimi" || !ID_PATTERN.test(grant.runId) || !ID_PATTERN.test(grant.networkId)
+        || !TASK_PATTERN.test(grant.taskId) || !SESSION_PATTERN.test(grant.sessionId)
+        || !ALIAS_PATTERN.test(grant.modelAlias) || !MODEL_PATTERN.test(grant.model)
+        || !Number.isSafeInteger(grant.ttlMs) || grant.ttlMs < 1 || grant.ttlMs > 3_600_000) {
+        throw new Error("Invalid Kimi broker grant")
+      }
+      const token = random(32).toString("base64url")
+      if (!TOKEN_PATTERN.test(token) || grants.has(token)) throw new Error("Invalid Kimi broker grant")
+      grants.set(token, {...grant, expiresAt: now() + grant.ttlMs, active: false})
+      return token
+    },
+    /** @param {string} token */
+    activate(token) {
+      const grant = currentGrant(grants, token, now)
+      if (grant.active) throw new Error("Kimi broker grant already active")
+      grant.active = true
+      return {...grant}
+    },
+    /** @param {string} token @param {{provider: string, runId: string, networkId: string, taskId: string, sessionId: string, modelAlias: string}} context */
+    authorize(token, context) {
+      const grant = currentGrant(grants, token, now)
+      if (grant.provider !== context.provider || grant.runId !== context.runId
+        || grant.networkId !== context.networkId || grant.taskId !== context.taskId
+        || grant.sessionId !== context.sessionId || grant.modelAlias !== context.modelAlias) {
+        throw new Error("Kimi broker grant lineage denied")
+      }
+      if (!grant.active) throw new Error("Kimi broker grant pending")
+      return {...grant}
+    },
+    /** @param {string} token */
+    revoke(token) { grants.delete(token) },
+    clear() { grants.clear() }
+  }
+}
+
+/**
+ * @param {Map<string, KimiGrant>} grants
+ * @param {string} token
+ * @param {() => number} now
+ */
+function currentGrant(grants, token, now) {
+  const grant = grants.get(token)
+  if (!grant) throw new Error("Kimi broker grant unknown token")
+  if (grant.expiresAt < now()) {
+    grants.delete(token)
+    throw new Error("Kimi broker grant expired")
+  }
+  return grant
+}
+
+/** @param {{method?: string, path?: string, headers?: Record<string, string | string[] | undefined>}} request */
+export function validateKimiBrokerRequest(request) {
+  if (request.method !== "POST" || request.path !== "/v1/chat/completions") {
+    throw new Error("Kimi broker request denied")
+  }
+  for (const header of Object.keys(request.headers ?? {})) {
+    if (!ALLOWED_HEADERS.has(header.toLowerCase())) throw new Error(`Kimi broker request denied header: ${header.toLowerCase()}`)
+  }
+  return {method: "POST", path: "/v1/chat/completions", upstreamPath: KIMI_CHAT_COMPLETIONS_PATH}
+}
+
+/** @param {Buffer} body @param {string} allowedModel */
+export function validateKimiChatBody(body, allowedModel) {
+  const text = body.toString("utf8")
+  if (topLevelKeyCount(text, "model") !== 1) throw denied()
+  let value
+  try { value = JSON.parse(text) } catch { throw denied() }
+  if (!record(value) || Object.keys(value).some((key) => !BODY_KEYS.has(key))) throw denied()
+  if (value.model !== allowedModel || !Array.isArray(value.messages) || value.stream !== true) throw denied()
+  if (value.messages.length === 0 || value.messages.length > 4096 || !value.messages.every(validMessage)) throw denied()
+  if (value.tools !== undefined && (!Array.isArray(value.tools) || value.tools.length > 512 || !value.tools.every(record))) throw denied()
+  if (value.stream_options !== undefined && (!record(value.stream_options)
+    || !exactKeys(value.stream_options, ["include_usage"]) || value.stream_options.include_usage !== true)) throw denied()
+  if (value.thinking !== undefined && !validThinking(value.thinking)) throw denied()
+  if (value.response_format !== undefined && !record(value.response_format)) throw denied()
+  if (value.prompt_cache_key !== undefined && (typeof value.prompt_cache_key !== "string" || value.prompt_cache_key.length > 512)) throw denied()
+  if (value.stop !== undefined && !validStop(value.stop)) throw denied()
+  for (const key of NUMERIC_KEYS) {
+    const item = value[key]
+    if (item !== undefined && (typeof item !== "number" || !Number.isFinite(item))) throw denied()
+  }
+  if (value.max_completion_tokens !== undefined && (typeof value.max_completion_tokens !== "number"
+    || !Number.isSafeInteger(value.max_completion_tokens)
+    || value.max_completion_tokens < 1 || value.max_completion_tokens > 1_000_000)) throw denied()
+  if (value.n !== undefined && value.n !== 1) throw denied()
+  return value
+}
+
+/** @param {unknown} value */
+function validMessage(value) {
+  if (!record(value) || typeof value.role !== "string" || !["system", "user", "assistant", "tool"].includes(value.role)) return false
+  const allowed = new Set(["role", "content", "tool_calls", "tool_call_id", "name", "reasoning_content", "reasoning_details", "reasoning", "tools"])
+  return Object.keys(value).every((key) => allowed.has(key))
+}
+
+/** @param {unknown} value */
+function validThinking(value) {
+  if (!record(value) || Object.keys(value).some((key) => !["type", "effort", "keep"].includes(key))) return false
+  if (value.type !== undefined && value.type !== "enabled" && value.type !== "disabled") return false
+  if (value.effort !== undefined && (typeof value.effort !== "string" || !/^[A-Za-z0-9_-]{1,32}$/u.test(value.effort))) return false
+  return value.keep === undefined || value.keep === "all"
+}
+
+/** @param {unknown} value */
+function validStop(value) {
+  return typeof value === "string" ? value.length <= 512
+    : Array.isArray(value) && value.length <= 16 && value.every((item) => typeof item === "string" && item.length <= 512)
+}
+
+/** @param {string | undefined} authorization */
+export function kimiBearerToken(authorization) {
+  const match = /^Bearer ([A-Za-z0-9_-]{32,128})$/u.exec(authorization ?? "")
+  if (!match || !TOKEN_PATTERN.test(match[1] ?? "")) throw new Error("Kimi broker grant format denied")
+  return /** @type {string} */ (match[1])
+}
+
+/** @param {string | undefined} value */
+export function parseApprovedKimiModels(value) {
+  let parsed
+  try { parsed = JSON.parse(value ?? "") } catch { throw new Error("THREADWIRE_ALLOWED_KIMI_MODELS must contain allowed Kimi models") }
+  if (!record(parsed) || Object.keys(parsed).length < 1 || Object.keys(parsed).length > 32) {
+    throw new Error("THREADWIRE_ALLOWED_KIMI_MODELS must contain allowed Kimi models")
+  }
+  /** @type {Map<string, ApprovedKimiModel>} */
+  const models = new Map()
+  for (const [alias, item] of Object.entries(parsed)) {
+    if (!ALIAS_PATTERN.test(alias) || !record(item) || !exactKeys(item, ["model", "protocol"])
+      || typeof item.model !== "string" || !MODEL_PATTERN.test(item.model) || item.protocol !== "kimi") {
+      throw new Error("THREADWIRE_ALLOWED_KIMI_MODELS must contain allowed Kimi models")
+    }
+    models.set(alias, {alias, model: item.model, protocol: "kimi"})
+  }
+  return models
+}
+
+/** @returns {Error} */
+function denied() { return new Error("Kimi broker request denied") }
+/** @param {unknown} value @returns {value is Record<string, unknown>} */
+function record(value) { return typeof value === "object" && value !== null && !Array.isArray(value) }
+/** @param {Record<string, unknown>} value @param {readonly string[]} keys */
+function exactKeys(value, keys) {
+  const actual = Object.keys(value).sort()
+  return actual.length === keys.length && actual.every((key, index) => key === [...keys].sort()[index])
+}
+
+/** @param {string} text @param {string} wanted @returns {number} */
+function topLevelKeyCount(text, wanted) {
+  let depth = 0
+  let count = 0
+  let index = 0
+  while (index < text.length) {
+    if (text[index] === "\"") {
+      let string = ""
+      index++
+      while (index < text.length && text[index] !== "\"") {
+        if (text[index] === "\\") { index += 2; continue }
+        string += text[index++]
+      }
+      if (depth === 1) {
+        let next = index + 1
+        while (/\s/u.test(text[next] ?? "")) next++
+        if (text[next] === ":" && string === wanted) count++
+      }
+    } else if (text[index] === "{") depth++
+    else if (text[index] === "}") depth--
+    index++
+  }
+  return count
+}

package/src/kimi-model-broker.js

@@ -0,0 +1,325 @@
+// @ts-check
+
+import {createServer} from "node:http"
+import {once} from "node:events"
+import {abortable} from "./absolute-deadline.js"
+import {
+  createKimiGrantStore,
+  kimiBearerToken,
+  parseApprovedKimiModels,
+  validateKimiBrokerRequest,
+  validateKimiChatBody
+} from "./kimi-model-broker-policy.js"
+import {openKimiOAuthStore} from "./kimi-oauth-store.js"
+
+const MAX_REQUEST_BYTES = 2_097_152
+const MAX_RESPONSE_BYTES = 8_388_608
+const UPSTREAM_URL = "https://api.kimi.com/coding/v1/chat/completions"
+
+/** @typedef {{provider: "kimi", runId: string, networkId: string, taskId: string, sessionId: string, modelAlias: string, model: string, ttlMs: number}} KimiGrant */
+/** @typedef {{alias: string, model: string, protocol: "kimi"}} ApprovedKimiModel */
+/** @typedef {ReturnType<typeof createKimiGrantStore>} KimiGrantStore */
+/** @typedef {Awaited<ReturnType<typeof openKimiOAuthStore>>} KimiOAuthStore */
+
+/** @param {{environment?: NodeJS.ProcessEnv, fetchImplementation?: typeof fetch, oauthFetchImplementation?: typeof fetch}} [options] */
+export async function startKimiModelBroker(options = {}) {
+  const environment = options.environment ?? process.env
+  const host = safeHost(environment.THREADWIRE_KIMI_MODEL_BROKER_HOST ?? "0.0.0.0")
+  const port = portValue(environment.THREADWIRE_KIMI_MODEL_BROKER_PORT, 8791)
+  const adminToken = authoritySetting(environment.THREADWIRE_KIMI_MODEL_BROKER_ADMIN_TOKEN, "THREADWIRE_KIMI_MODEL_BROKER_ADMIN_TOKEN")
+  const approvedModels = parseApprovedKimiModels(environment.THREADWIRE_ALLOWED_KIMI_MODELS)
+  const oauth = await openKimiOAuthStore({
+    file: safeSetting(environment.THREADWIRE_KIMI_OAUTH_FILE, "THREADWIRE_KIMI_OAUTH_FILE"),
+    fetchImplementation: options.oauthFetchImplementation ?? fetch
+  })
+  const fetchImplementation = options.fetchImplementation ?? fetch
+  const grants = createKimiGrantStore()
+  /** @type {Map<string, import("node:http").Server>} */
+  const listeners = new Map()
+  /** @type {Map<string, {controller: AbortController, timer: NodeJS.Timeout, sockets: Set<import("node:net").Socket>}>} */
+  const runtimes = new Map()
+  /** @type {Set<import("node:net").Socket>} */
+  const controlSockets = new Set()
+  let stopping = false
+
+  /** @param {string} token */
+  const revokeGrant = async (token) => {
+    grants.revoke(token)
+    const runtime = runtimes.get(token)
+    runtimes.delete(token)
+    if (runtime !== undefined) {
+      clearTimeout(runtime.timer)
+      runtime.controller.abort(new Error("Kimi broker grant revoked"))
+      for (const socket of runtime.sockets) socket.destroy()
+      runtime.sockets.clear()
+    }
+    await closeListener(listeners, token)
+  }
+
+  const server = createServer(async (request, response) => {
+    try {
+      if (stopping) throw new Error("Kimi model broker is shutting down")
+      if (request.method === "GET" && request.url === "/healthz") {
+        const health = await oauth.health()
+        sendJson(response, health.ready ? 200 : 503, health.ready
+          ? {ok: true, models: approvedModels.size}
+          : {ok: false, needsLogin: true})
+        return
+      }
+      requireAdmin(request.headers.authorization, adminToken)
+      if (request.method === "POST" && request.url === "/admin/grants") {
+        const health = await oauth.health()
+        if (!health.ready) throw new Error("Kimi OAuth login required")
+        const body = await readJson(request)
+        const selection = parseGrant(body, approvedModels)
+        const token = grants.issue(selection.grant)
+        const controller = new AbortController()
+        /** @type {Set<import("node:net").Socket>} */
+        const sockets = new Set()
+        const listener = createServer((workerRequest, workerResponse) => {
+          proxyWorkerRequest(workerRequest, workerResponse, {
+            token, grant: selection.grant, grants, oauth, fetchImplementation, signal: controller.signal
+          }).catch((error) => {
+            if (workerResponse.destroyed) return
+            const status = clientError(error) ? 403 : 502
+            sendJson(workerResponse, status, {error: status === 403 ? "request denied" : "Kimi model broker unavailable"})
+          })
+        })
+        listener.on("connection", (socket) => {
+          if (controller.signal.aborted) return socket.destroy()
+          sockets.add(socket)
+          socket.once("close", () => sockets.delete(socket))
+        })
+        try { await listen(listener, 0, selection.brokerAddress) } catch (error) {
+          grants.revoke(token)
+          throw error
+        }
+        listeners.set(token, listener)
+        const timer = setTimeout(() => { void revokeGrant(token) }, selection.grant.ttlMs)
+        timer.unref()
+        runtimes.set(token, {controller, timer, sockets})
+        const address = listener.address()
+        if (address === null || typeof address === "string") throw new Error("Kimi broker listener unavailable")
+        sendJson(response, 201, {token, port: address.port})
+        return
+      }
+      if (request.method === "POST" && request.url?.startsWith("/admin/grants/") && request.url.endsWith("/activate")) {
+        const token = decodeURIComponent(request.url.slice("/admin/grants/".length, -"/activate".length))
+        grants.activate(token)
+        sendJson(response, 200, {ok: true})
+        return
+      }
+      if (request.method === "DELETE" && request.url?.startsWith("/admin/grants/")) {
+        const token = decodeURIComponent(request.url.slice("/admin/grants/".length))
+        await revokeGrant(token)
+        response.writeHead(204)
+        response.end()
+        return
+      }
+      sendJson(response, 403, {error: "request denied"})
+    } catch (error) {
+      const status = clientError(error) ? 403 : 503
+      sendJson(response, status, {error: status === 403 ? "request denied" : "Kimi model broker unavailable"})
+    }
+  })
+  server.on("connection", (socket) => {
+    controlSockets.add(socket)
+    socket.once("close", () => controlSockets.delete(socket))
+  })
+  await listen(server, port, host)
+  return {
+    server,
+    activeListeners: () => listeners.size,
+    close: async () => {
+      if (stopping) return
+      stopping = true
+      for (const socket of controlSockets) socket.destroy()
+      await Promise.all([...listeners.keys()].map(revokeGrant))
+      await boundedClose(server)
+    },
+    config: {host, port, models: [...approvedModels.keys()]}
+  }
+}
+
+/**
+ * @param {import("node:http").IncomingMessage} request
+ * @param {import("node:http").ServerResponse} response
+ * @param {{token: string, grant: KimiGrant, grants: KimiGrantStore, oauth: KimiOAuthStore, fetchImplementation: typeof fetch, signal: AbortSignal}} options
+ */
+async function proxyWorkerRequest(request, response, options) {
+  throwIfAborted(options.signal)
+  const policyHeaders = {...request.headers}
+  delete policyHeaders.host
+  delete policyHeaders.connection
+  delete policyHeaders["transfer-encoding"]
+  validateKimiBrokerRequest({method: request.method ?? "", path: request.url ?? "", headers: policyHeaders})
+  const token = kimiBearerToken(request.headers.authorization)
+  if (token !== options.token) throw new Error("Kimi broker request denied")
+  const context = {
+    provider: "kimi", runId: options.grant.runId,
+    networkId: options.grant.networkId, taskId: options.grant.taskId,
+    sessionId: options.grant.sessionId, modelAlias: options.grant.modelAlias
+  }
+  const grant = options.grants.authorize(token, context)
+  const body = await readBody(request, options.signal)
+  options.grants.authorize(token, context)
+  validateKimiChatBody(body, grant.model)
+  const accessToken = await options.oauth.getAccessToken({signal: options.signal})
+  throwIfAborted(options.signal)
+  const upstream = await abortable(options.fetchImplementation(UPSTREAM_URL, {
+    method: "POST",
+    redirect: "error",
+    headers: {
+      authorization: `Bearer ${accessToken}`,
+      "content-type": "application/json",
+      accept: "text/event-stream",
+      "user-agent": "threadwire-kimi-model-broker/1"
+    },
+    body,
+    signal: options.signal
+  }), options.signal)
+  throwIfAborted(options.signal)
+  const contentType = safeContentType(upstream.headers.get("content-type"))
+  response.writeHead(upstream.status, {"content-type": contentType, "cache-control": "no-store"})
+  await streamResponse(upstream, response, options.signal)
+}
+
+/** @param {Response} upstream @param {import("node:http").ServerResponse} response @param {AbortSignal} signal */
+async function streamResponse(upstream, response, signal) {
+  if (upstream.body === null) { response.end(); return }
+  const reader = upstream.body.getReader()
+  let bytes = 0
+  try {
+    while (true) {
+      throwIfAborted(signal)
+      const {done, value} = await reader.read()
+      if (done) break
+      bytes += value.byteLength
+      if (bytes > MAX_RESPONSE_BYTES) throw new Error("Kimi broker response exceeded capacity")
+      if (!response.write(Buffer.from(value))) await abortable(once(response, "drain"), signal)
+    }
+    response.end()
+  } catch (error) {
+    await reader.cancel().catch(() => {})
+    response.destroy(error instanceof Error ? error : undefined)
+    throw error
+  } finally { reader.releaseLock() }
+}
+
+/** @param {unknown} value @param {Map<string, ApprovedKimiModel>} approvedModels @returns {{brokerAddress: string, grant: KimiGrant}} */
+function parseGrant(value, approvedModels) {
+  if (!record(value) || !exactKeys(value, ["brokerAddress", "modelAlias", "networkId", "provider", "runId", "sessionId", "taskId", "ttlMs"])
+    || value.provider !== "kimi" || typeof value.runId !== "string" || typeof value.networkId !== "string"
+    || typeof value.taskId !== "string" || typeof value.sessionId !== "string"
+    || typeof value.modelAlias !== "string" || typeof value.brokerAddress !== "string" || typeof value.ttlMs !== "number") {
+    throw new Error("Invalid Kimi broker grant")
+  }
+  if (!/^(?:\d{1,3}\.){3}\d{1,3}$/u.test(value.brokerAddress)) throw new Error("Invalid Kimi broker grant")
+  const model = approvedModels.get(value.modelAlias)
+  if (model === undefined) throw new Error("Kimi model is not allowed")
+  return {
+    brokerAddress: value.brokerAddress,
+    grant: {
+      provider: "kimi", runId: value.runId, networkId: value.networkId,
+      taskId: value.taskId, sessionId: value.sessionId,
+      modelAlias: model.alias, model: model.model, ttlMs: value.ttlMs
+    }
+  }
+}
+
+/** @param {import("node:http").IncomingMessage} request @returns {Promise<unknown>} */
+async function readJson(request) {
+  const body = await readBody(request)
+  try { return JSON.parse(body.toString("utf8")) } catch { throw new Error("Invalid Kimi broker request") }
+}
+
+/** @param {import("node:http").IncomingMessage} request @param {AbortSignal | undefined} [signal] @returns {Promise<Buffer>} */
+async function readBody(request, signal) {
+  /** @type {Buffer[]} */
+  const chunks = []
+  let size = 0
+  for await (const chunk of request) {
+    throwIfAborted(signal)
+    const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk)
+    size += buffer.length
+    if (size > MAX_REQUEST_BYTES) throw new Error("Kimi broker request exceeded capacity")
+    chunks.push(buffer)
+  }
+  throwIfAborted(signal)
+  return Buffer.concat(chunks)
+}
+
+/** @param {AbortSignal | undefined} signal */
+function throwIfAborted(signal) {
+  if (signal?.aborted) throw signal.reason instanceof Error ? signal.reason : new Error("Kimi broker request aborted")
+}
+/** @param {string | undefined} value @param {string} expected */
+function requireAdmin(value, expected) {
+  if (value !== `Bearer ${expected}`) throw new Error("Kimi broker request denied")
+}
+/** @param {string | undefined} value @param {string} name @returns {string} */
+function safeSetting(value, name) {
+  if (typeof value !== "string" || value.length === 0 || /[\0\r\n]/u.test(value)) throw new Error(`${name} is required`)
+  return value
+}
+/** @param {string | undefined} value @param {string} name @returns {string} */
+function authoritySetting(value, name) {
+  const authority = safeSetting(value, name)
+  if (authority.length < 32 || authority.length > 512) throw new Error(`${name} must be at least 32 characters`)
+  return authority
+}
+/** @param {string} value @returns {string} */
+function safeHost(value) {
+  if (value !== "0.0.0.0" && value !== "127.0.0.1" && value !== "::") throw new Error("Invalid Kimi model broker host")
+  return value
+}
+/** @param {string | undefined} value @param {number} fallback @returns {number} */
+function portValue(value, fallback) {
+  if (value === undefined) return fallback
+  const number = Number(value)
+  if (!/^\d+$/u.test(value) || !Number.isSafeInteger(number) || number < 1 || number > 65535) throw new Error("Invalid Kimi model broker port")
+  return number
+}
+/** @param {string | null} value @returns {string} */
+function safeContentType(value) {
+  return value && /^[\w.+-]+\/[\w.+-]+(?:;\s*charset=[\w-]+)?$/u.test(value) ? value : "application/octet-stream"
+}
+/** @param {import("node:http").ServerResponse} response @param {number} status @param {unknown} value */
+function sendJson(response, status, value) {
+  if (response.headersSent || response.destroyed) return
+  response.writeHead(status, {"content-type": "application/json", "cache-control": "no-store"})
+  response.end(JSON.stringify(value))
+}
+/** @param {unknown} error @returns {boolean} */
+function clientError(error) {
+  return error instanceof Error && /(denied|invalid|unknown token|expired|pending|already active|not allowed)/iu.test(error.message)
+}
+/** @param {unknown} value @returns {value is Record<string, unknown>} */
+function record(value) { return typeof value === "object" && value !== null && !Array.isArray(value) }
+/** @param {Record<string, unknown>} value @param {readonly string[]} expected @returns {boolean} */
+function exactKeys(value, expected) {
+  const actual = Object.keys(value).sort()
+  const wanted = [...expected].sort()
+  return actual.length === wanted.length && actual.every((key, index) => key === wanted[index])
+}
+/** @param {import("node:http").Server} server @param {number} port @param {string} host @returns {Promise<void>} */
+function listen(server, port, host) {
+  return new Promise((resolve, reject) => {
+    server.once("error", reject)
+    server.listen(port, host, () => { server.off("error", reject); resolve(undefined) })
+  })
+}
+/** @param {import("node:http").Server} server @returns {Promise<void>} */
+function boundedClose(server) {
+  return Promise.race([
+    new Promise((resolve) => server.close(() => resolve(undefined))),
+    new Promise((resolve) => { const timer = setTimeout(resolve, 1000); timer.unref() })
+  ])
+}
+/** @param {Map<string, import("node:http").Server>} listeners @param {string} token */
+async function closeListener(listeners, token) {
+  const listener = listeners.get(token)
+  listeners.delete(token)
+  if (listener === undefined) return
+  await boundedClose(listener)
+}