fix(inference): authenticate managed llama.cpp bridge

src/lib/onboard/runtime-provider/docker-llama-cpp-managed-lifecycle.test.ts

@@ -405,6 +405,7 @@ describe("dormant Docker llama.cpp managed lifecycle", () => {
     expect(privateBridge.start).toHaveBeenCalledWith(
       expect.objectContaining({
         transactionId: TRANSACTION_ID,
+        apiKeyPath: runtimeBindings.apiKeyHostPath,
         targetHost: "172.30.0.2",
         bindAddresses: ["127.0.0.1", "172.29.0.1"],
       }),

src/lib/onboard/runtime-provider/docker-llama-cpp-managed-lifecycle.ts

@@ -962,6 +962,7 @@ function privateBridgeAuthority(
   }
   return Object.freeze({
     transactionId: journal.transactionId,
+    apiKeyPath: options.bindings.apiKeyHostPath,
     targetHost: container.containerIp,
     targetPort: options.contract.serve.port,
     listenPort: options.bindings.hostPort,

src/lib/onboard/runtime-provider/docker-llama-cpp-private-bridge-process.ts

@@ -1,9 +1,21 @@
 // SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
 // SPDX-License-Identifier: Apache-2.0
 
+import { timingSafeEqual } from "node:crypto";
+import fs from "node:fs";
+import http from "node:http";
 import net from "node:net";
 
 const SHA256 = /^[a-f0-9]{64}$/u;
+const API_KEY_FILE_DESCRIPTOR = 3;
+const AUTH_MODE = "api-key-fd3";
+const UNAUTHORIZED_BODY = `${JSON.stringify({
+  error: {
+    code: "unauthorized",
+    message: "Authentication is required.",
+    type: "authentication_error",
+  },
+})}\n`;
 
 export interface LlamaCppPrivateBridgeArguments {
   readonly transactionId: string;
@@ -53,6 +65,7 @@ export function parseLlamaCppPrivateBridgeArguments(
   const bindAddresses = values.get("--bind-address") ?? [];
   const supported = new Set([
     "--transaction",
+    "--auth-mode",
     "--target-host",
     "--target-port",
     "--listen-port",
@@ -63,6 +76,7 @@ export function parseLlamaCppPrivateBridgeArguments(
   }
   if (
     !SHA256.test(transactionId) ||
+    one("--auth-mode") !== AUTH_MODE ||
     !isPrivateIpv4(targetHost) ||
     bindAddresses.length !== 2 ||
     bindAddresses[0] !== "127.0.0.1" ||
@@ -83,31 +97,149 @@ export function parseLlamaCppPrivateBridgeArguments(
   });
 }
 
+function readPrivateBridgeApiKey(): string {
+  let value: string;
+  try {
+    value = fs.readFileSync(API_KEY_FILE_DESCRIPTOR, "utf8").trim();
+  } catch {
+    throw new Error("private bridge credential is unavailable");
+  } finally {
+    try {
+      fs.closeSync(API_KEY_FILE_DESCRIPTOR);
+    } catch {
+      // The inherited descriptor can already be closed after a failed read.
+    }
+  }
+  if (!SHA256.test(value)) {
+    throw new Error("private bridge credential is invalid");
+  }
+  return value;
+}
+
+function authorizationValues(request: http.IncomingMessage): readonly string[] {
+  const values: string[] = [];
+  for (let index = 0; index < request.rawHeaders.length; index += 2) {
+    if (request.rawHeaders[index]?.toLowerCase() === "authorization") {
+      values.push(request.rawHeaders[index + 1] ?? "");
+    }
+  }
+  return values;
+}
+
+function hasValidBearerCredential(request: http.IncomingMessage, apiKey: string): boolean {
+  const values = authorizationValues(request);
+  if (values.length !== 1) return false;
+  const value = values[0]!;
+  if (value.length !== 7 + apiKey.length || value.slice(0, 7).toLowerCase() !== "bearer ") {
+    return false;
+  }
+  const supplied = Buffer.from(value.slice(7), "utf8");
+  const expected = Buffer.from(apiKey, "utf8");
+  return supplied.length === expected.length && timingSafeEqual(supplied, expected);
+}
+
+function isUnauthenticatedHealthProbe(request: http.IncomingMessage): boolean {
+  return request.method === "GET" && request.url === "/health";
+}
+
+function writeUnauthorized(response: http.ServerResponse): void {
+  response.writeHead(401, {
+    "Cache-Control": "no-store",
+    "Content-Length": Buffer.byteLength(UNAUTHORIZED_BODY),
+    "Content-Type": "application/json",
+    "WWW-Authenticate": "Bearer",
+    "X-Content-Type-Options": "nosniff",
+  });
+  response.end(UNAUTHORIZED_BODY);
+}
+
+function writeUpstreamUnavailable(response: http.ServerResponse): void {
+  if (response.destroyed || response.writableEnded) return;
+  if (response.headersSent) {
+    response.destroy();
+    return;
+  }
+  const body = `${JSON.stringify({
+    error: {
+      code: "upstream_unavailable",
+      message: "The managed inference server is unavailable.",
+      type: "server_error",
+    },
+  })}\n`;
+  response.writeHead(502, {
+    "Cache-Control": "no-store",
+    "Content-Length": Buffer.byteLength(body),
+    "Content-Type": "application/json",
+    "X-Content-Type-Options": "nosniff",
+  });
+  response.end(body);
+}
+
+export function createLlamaCppPrivateBridgeRequestHandler(
+  authority: Pick<LlamaCppPrivateBridgeArguments, "targetHost" | "targetPort">,
+  apiKey: string,
+): http.RequestListener {
+  if (
+    !SHA256.test(apiKey) ||
+    (!isPrivateIpv4(authority.targetHost) && authority.targetHost !== "127.0.0.1")
+  ) {
+    throw new Error("private bridge HTTP authority is invalid");
+  }
+  const targetPort = exactPort(String(authority.targetPort), "target port");
+  const canonicalAuthorization = `Bearer ${apiKey}`;
+
+  return (request, response) => {
+    const healthProbe = isUnauthenticatedHealthProbe(request);
+    if (!healthProbe && !hasValidBearerCredential(request, apiKey)) {
+      request.resume();
+      writeUnauthorized(response);
+      return;
+    }
+
+    const headers: http.OutgoingHttpHeaders = { ...request.headers };
+    headers.host = `${authority.targetHost}:${String(targetPort)}`;
+    if (!healthProbe) headers.authorization = canonicalAuthorization;
+    delete headers.forwarded;
+    delete headers["x-forwarded-for"];
+    delete headers["x-forwarded-host"];
+    delete headers["x-forwarded-proto"];
+
+    const upstream = http.request(
+      {
+        headers,
+        host: authority.targetHost,
+        method: request.method,
+        path: request.url,
+        port: targetPort,
+      },
+      (upstreamResponse) => {
+        response.writeHead(upstreamResponse.statusCode ?? 502, upstreamResponse.headers);
+        upstreamResponse.once("error", () => response.destroy());
+        upstreamResponse.pipe(response);
+      },
+    );
+    upstream.once("error", () => writeUpstreamUnavailable(response));
+    request.once("aborted", () => upstream.destroy());
+    request.once("error", () => upstream.destroy());
+    response.once("close", () => {
+      if (!response.writableEnded) upstream.destroy();
+    });
+    request.pipe(upstream);
+  };
+}
+
 export async function runLlamaCppPrivateBridge(
   authority: LlamaCppPrivateBridgeArguments,
+  apiKey: string,
 ): Promise<void> {
-  const servers = authority.bindAddresses.map((host) =>
-    net.createServer({ allowHalfOpen: false, pauseOnConnect: true }, (client) => {
-      const upstream = net.createConnection({
-        host: authority.targetHost,
-        port: authority.targetPort,
-      });
-      const close = () => {
-        client.destroy();
-        upstream.destroy();
-      };
-      client.on("error", close);
-      upstream.on("error", close);
-      upstream.once("connect", () => {
-        client.pipe(upstream);
-        upstream.pipe(client);
-        client.resume();
-      });
-    }),
-  );
+  const handler = createLlamaCppPrivateBridgeRequestHandler(authority, apiKey);
+  const servers = authority.bindAddresses.map(() => http.createServer(handler));
 
   const close = () => {
-    for (const server of servers) server.close();
+    for (const server of servers) {
+      server.close();
+      server.closeAllConnections();
+    }
   };
   process.once("SIGINT", close);
   process.once("SIGTERM", close);
@@ -130,10 +262,15 @@ export async function runLlamaCppPrivateBridge(
 }
 
 if (require.main === module) {
-  runLlamaCppPrivateBridge(parseLlamaCppPrivateBridgeArguments(process.argv.slice(2))).catch(
-    (error: unknown) => {
+  Promise.resolve()
+    .then(() =>
+      runLlamaCppPrivateBridge(
+        parseLlamaCppPrivateBridgeArguments(process.argv.slice(2)),
+        readPrivateBridgeApiKey(),
+      ),
+    )
+    .catch((error: unknown) => {
       console.error(error instanceof Error ? error.message : String(error));
       process.exitCode = 1;
-    },
-  );
+    });
 }