fix(inference): authenticate managed llama.cpp bridge (#9670)

## Summary

- replace the managed llama.cpp raw TCP bridge with an HTTP bridge that
enforces one Bearer credential
- pass the managed API key through inherited file descriptor 3 after
validating the key file's ownership, mode, type, link count, and
identity
- preserve unauthenticated lifecycle probing only for exact `GET
/health`
- replace legacy pre-authentication bridge processes during lifecycle
recovery
- add focused coverage for missing, invalid, duplicate, and valid
credentials, health-route boundaries, upstream failure, descriptor
inheritance, legacy replacement, and secure credential-file validation

## Root cause

The managed llama.cpp container required its configured API key, but the
host bridge was a transparent TCP proxy. Requests to the host loopback
listener therefore reached the container without bridge-layer
authentication and could bypass the intended managed-route boundary.

## Impact

Requests to the managed bridge now fail closed unless they carry exactly
one valid Bearer credential. The credential is never placed in process
arguments or environment variables. The exact health probe remains
available to lifecycle management, and resume/recovery replaces older
bridge processes that lack the authenticated mode marker.

## Validation

- 73 focused Vitest tests passed
- `npm run typecheck:cli` passed
- `npm run checks:repository` passed
- targeted Oxlint passed
- commit hooks, repository checks, and secret scanning passed
- verified live on NVIDIA DGX Spark with managed llama.cpp and Muse
Glimmer; detailed credential-redacted proof is included in a PR comment

Fixes #9591

Signed-off-by: Prekshi Vyas <prekshiv@nvidia.com>

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **Security Enhancements**
  * Added API-key authentication for private bridge connections.
* Restricted health checks to unauthenticated access while protecting
other requests.
  * Added secure validation and handling for API-key files.
  * Standardized authorization forwarding and improved error responses.

* **Bug Fixes**
  * Private bridge startup now uses the configured API-key path.
* Improved handling of invalid credentials and upstream connection
failures.
* Strengthened pull request validation to prevent mismatched workflow
revisions.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Signed-off-by: Senthil Ravichandran <senthilr@nvidia.com>
Co-authored-by: Senthil Ravichandran <senthilr@nvidia.com>

Author: prekshivyas

.github/workflows/pr-self-hosted.yaml

@@ -28,17 +28,7 @@ concurrency:
   cancel-in-progress: true
 
 jobs:
-  get-pr-info:
-    runs-on: ubuntu-latest
-    timeout-minutes: 5
-    outputs:
-      pr-info: ${{ steps.get-pr-info.outputs.pr-info }}
-    steps:
-      - id: get-pr-info
-        uses: nv-gha-runners/get-pr-info@090577647b8ddc4e06e809e264f7881650ecdccf # main
-
   select-llama-cpp-generic-gpu:
-    needs: get-pr-info
     runs-on: ubuntu-latest
     timeout-minutes: 5
     outputs:
@@ -48,12 +38,16 @@ jobs:
         name: Select llama.cpp generic GPU E2E from PR files
         env:
           GH_TOKEN: ${{ github.token }}
-          PR_INFO: ${{ needs.get-pr-info.outputs.pr-info }}
         shell: bash
         run: |
           set -euo pipefail
-          pr_number="$(jq -er '.number | select(type == "number" and . > 0)' <<<"$PR_INFO")"
-          head_sha="$(jq -er '.head.sha | select(test("^[a-f0-9]{40}$"))' <<<"$PR_INFO")"
+          [[ "$GITHUB_REF_NAME" =~ ^pull-request/([0-9]+)$ ]] || {
+            echo "::error::Copied branch name does not identify a PR" >&2
+            exit 1
+          }
+          pr_number="${BASH_REMATCH[1]}"
+          pr_json="$(gh api "repos/$GITHUB_REPOSITORY/pulls/$pr_number")"
+          head_sha="$(jq -er '.head.sha | select(test("^[a-f0-9]{40}$"))' <<<"$pr_json")"
           [[ "$head_sha" == "$GITHUB_SHA" ]] || {
             echo "::error::Copied PR branch SHA does not match the current PR head" >&2
             exit 1
@@ -89,9 +83,7 @@ jobs:
 
   llama-cpp-generic-gpu:
     name: llama.cpp on generic NVIDIA GPU
-    needs:
-      - get-pr-info
-      - select-llama-cpp-generic-gpu
+    needs: select-llama-cpp-generic-gpu
     if: ${{ needs.select-llama-cpp-generic-gpu.outputs.selected == 'true' }}
     runs-on: linux-amd64-gpu-rtxpro6000-latest-1
     timeout-minutes: 120
@@ -101,9 +93,9 @@ jobs:
       E2E_TARGET_ID: llama-cpp-generic-gpu
       NEMOCLAW_ACCEPT_THIRD_PARTY_SOFTWARE: "1"
       NEMOCLAW_CLI_BIN: ${{ github.workspace }}/bin/nemoclaw.js
-      NEMOCLAW_E2E_EXPECTED_SHA: ${{ fromJSON(needs.get-pr-info.outputs.pr-info).head.sha }}
+      NEMOCLAW_E2E_EXPECTED_SHA: ${{ github.sha }}
       NEMOCLAW_E2E_SHARD: default
-      NEMOCLAW_LLAMA_CPP_QUALIFICATION_HEAD_SHA: ${{ fromJSON(needs.get-pr-info.outputs.pr-info).head.sha }}
+      NEMOCLAW_LLAMA_CPP_QUALIFICATION_HEAD_SHA: ${{ github.sha }}
       NEMOCLAW_LLAMACPP_RECIPE: llama-cpp.nemotron-3-nano-30b-a3b.spark-single.v1
       NEMOCLAW_NON_INTERACTIVE: "1"
       NEMOCLAW_PROVIDER: install-llama-cpp
@@ -115,7 +107,7 @@ jobs:
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
-          ref: ${{ fromJSON(needs.get-pr-info.outputs.pr-info).head.sha }}
+          ref: ${{ github.sha }}
 
       - name: Prepare E2E workspace
         uses: NVIDIA/NemoClaw/.github/actions/prepare-e2e@f6304bc25fc35bfaa441c8c2fbfee38f72805a75

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,151 @@ 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("close", () => {
+      if (!request.complete) 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 +264,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;
-    },
-  );
+    });
 }