Scope the OpenAPI credential to the proxy operations; test a keyed preflight

From the verification round on e65ea8a, which found both fixes closed
and no regression:

- The optional credential moves from the document root onto the two
  proxy operations. /v1/node-info is served by nvpair-node-info, which
  has no key gate.
- A preflight that carries a valid key is tested: routed like any
  authenticated request, with the key stripped.
- The key-file refusal names group access and points at
  NVPAIR_PROXY_API_KEYS, and the package doc, SECURITY.md and the
  troubleshooting page say group-readable rather than only
  other-readable. SECURITY.md reconciles "prefer the file" with the
  Kubernetes guidance, and troubleshooting lists a malformed inline
  key or allowlist entry as a cause of 403 loopback-only.
- The proxy README scopes its preflight description to loopback
  callers.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BSXRLJk5knQd4rNnn7XH1S
Signed-off-by: Aaron K. Clark <cryptojones@owasp.org>

Author: CryptoJones

SECURITY.md

@@ -106,8 +106,10 @@ run on a different host so that PAIR sees its real address.
 
 The gate compares keys in constant time, holds file keys in memory only as
 digests (a key supplied inline through the environment also remains in the
-process environment in clear, so prefer the file), never logs a presented key
-(a rejection logs a short digest fingerprint), and fails closed: a key file that other users can read (judged by Unix permission
+process environment in clear, so prefer the file where the proxy's own user or
+root can own it privately; on Kubernetes that is not possible without a
+group-readable mount, so use the variable there), never logs a presented key
+(a rejection logs a short digest fingerprint), and fails closed: a key file that its group or other users can read (judged by Unix permission
 bits; on Windows the check is skipped and the per-user data directory's ACL is
 the protection), that contains a malformed entry, or that cannot be read
 contributes no keys. That is judged per source: a rejected file does not

docs/troubleshooting.mdx

@@ -104,8 +104,11 @@ authenticated access with an API key; refer to
 The refusal then says what is missing:
 
 - `403` `loopback-only`: the node has no usable key configured. Check the node's
-  log; a key file that other users can read, or that contains a malformed entry,
-  is ignored and the reason is logged.
+  log; a key file that its group or other users can read, or that contains a
+  malformed entry,
+  is ignored and the reason is logged. A malformed `NVPAIR_PROXY_API_KEYS` or
+  `NVPAIR_PROXY_ALLOWED_CIDRS` entry turns authenticated access off entirely
+  until it is corrected.
 - `401` `unauthorized`: the request carried no key, or a key the node does not
   have. Send it as `Authorization: Bearer <key>` (or `X-Api-Key: <key>`). The
   node's log shows the first eight hex digits of the SHA-256 of the key it

fern/openapi.yml

@@ -34,18 +34,18 @@ tags:
     description: OpenAI-compatible inference proxied to an eligible node.
   - name: Node info
     description: Read-only node telemetry polled from discovered PAIR nodes.
-# A credential is optional: loopback callers send none, and a caller on another
-# machine needs one only when the node's operator has enabled LAN access.
-security:
-  - {}
-  - bearerAuth: []
-  - apiKeyAuth: []
 paths:
   /api/chat:
     post:
       tags:
         - Ollama-compatible
       operationId: ollamaChat
+      # Optional: loopback callers send no credential; a caller on another
+      # machine needs one only when the operator has enabled LAN access.
+      security:
+        - {}
+        - bearerAuth: []
+        - apiKeyAuth: []
       summary: Ollama-compatible chat
       description: >
         Send an Ollama-compatible chat request to the local PAIR proxy. PAIR
@@ -100,6 +100,12 @@ paths:
       tags:
         - OpenAI-compatible
       operationId: createChatCompletion
+      # Optional: loopback callers send no credential; a caller on another
+      # machine needs one only when the operator has enabled LAN access.
+      security:
+        - {}
+        - bearerAuth: []
+        - apiKeyAuth: []
       summary: OpenAI-compatible chat completion
       description: >
         Send an OpenAI-compatible chat completion request to the local PAIR

services/nvpair-proxy/README.md

@@ -151,7 +151,7 @@ sit on the engine's own port. The stored value predates the current default.
 
 **Browser clients (CORS).** PAIR does not enable CORS or add default browser permissions. Configure origins through the engine; its built-in defaults and user configuration remain authoritative. Ordinary forwarded responses preserve the upstream status, body, and CORS headers, including missing headers. A denial is never replaced with a successful OPTIONS response or retried to find permission elsewhere. Proxy-generated errors carry their actual status without CORS permission headers, so browser JavaScript may see a generic CORS failure while curl and diagnostics show the real error.
 
-A browser preflight (OPTIONS with Origin and Access-Control-Request-Method) queries every currently routable target, with concurrency eight, a ten-second query deadline, and no redirects. A single target's response is relayed. Multiple responding targets must all permit the requested origin, method, and headers; PAIR grants only their shared permissions. Credentials require unanimous explicit support. Synthesized preflights allow browsers to cache the result for 60 seconds; PAIR itself does not cache decisions. A policy denial returns 403. Unavailable targets are skipped; if none can answer, the proxy returns 502. Ordinary OPTIONS requests retain normal routing. Preflights do not create inference jobs or reserve scheduler capacity. Paired ingress forwards only to its local engine.
+A browser preflight (OPTIONS with Origin and Access-Control-Request-Method) from a loopback caller queries every currently routable target, with concurrency eight, a ten-second query deadline, and no redirects. A single target's response is relayed. Multiple responding targets must all permit the requested origin, method, and headers; PAIR grants only their shared permissions. Credentials require unanimous explicit support. Synthesized preflights allow browsers to cache the result for 60 seconds; PAIR itself does not cache decisions. A policy denial returns 403. Unavailable targets are skipped; if none can answer, the proxy returns 502. Ordinary OPTIONS requests retain normal routing. Preflights do not create inference jobs or reserve scheduler capacity. Paired ingress forwards only to its local engine. A preflight from another machine gets no exemption from the API-key gate: without a key it is refused with 401 before any target is queried, so a web page on another machine is not a supported client.
 
 Combined model lists forward the caller's origin and end-to-end headers, excluding Authorization and Cookie so credentials are not shared across engines. Multi-target preflights apply the same credential filtering. With an Origin header, every responding engine must return a valid list and permit sharing: one denial returns 403 and one invalid list returns 502, without partial inventory. An invalid-list error retains the combined CORS permissions when every responding engine allows the origin. Unavailable engines are skipped, with 502 returned when none can answer. Successful lists combine origin/credential permissions and Vary requirements. Requests without Origin retain partial aggregation when some inventories are unavailable. Engines without CORS support remain unavailable to cross-origin browser clients through PAIR.
 

services/nvpair-proxy/ingress_auth_test.go

@@ -109,7 +109,7 @@ func TestHandlePlainXApiKeyAccepted(t *testing.T) {
 
 // TestHandlePlainNonLoopbackWithoutKeyIs401: an enabled gate turns the LAN
 // refusal from 403 loopback-only into 401 with a challenge, and nothing is
-// forwarded. The refusal grants no CORS: a browser is not a supported LAN client.
+// forwarded.
 func TestHandlePlainNonLoopbackWithoutKeyIs401(t *testing.T) {
 	f, seen := lanProxy(t)
 	rec := httptest.NewRecorder()
@@ -288,3 +288,27 @@ func (c *countingReader) Read(b []byte) (int, error) {
 	c.n.Add(int64(n))
 	return n, err
 }
+
+// TestHandlePlainKeyedPreflightIsRouted: a preflight that does carry a valid key
+// is routed like any authenticated request, with the key stripped.
+func TestHandlePlainKeyedPreflightIsRouted(t *testing.T) {
+	f, seen := lanProxy(t)
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodOptions, "/v1/chat/completions", nil)
+	req.RemoteAddr = lanRemote
+	req.Header.Set("Origin", "http://app.test")
+	req.Header.Set("Access-Control-Request-Method", "POST")
+	req.Header.Set("Authorization", "Bearer "+lanKey)
+	f.handlePlain(rec, req)
+
+	if rec.Code == http.StatusUnauthorized || rec.Code == http.StatusForbidden {
+		t.Fatalf("keyed LAN preflight status = %d, want it routed", rec.Code)
+	}
+	h := seen.Load()
+	if h == nil {
+		t.Fatal("a keyed preflight never reached the engine")
+	}
+	if got := h.Get("Authorization"); got != "" {
+		t.Errorf("engine saw Authorization %q, want it stripped", got)
+	}
+}

services/shared/ingressauth/ingressauth.go

@@ -17,8 +17,8 @@
 // Loopback callers are never asked for a key — the desktop application, the
 // terminal interface, and local tools are unaffected by enabling the gate.
 //
-// Every failure fails closed. A key file that cannot be read, is readable by
-// other users, or contains an entry that could never match over the wire
+// Every failure fails closed. A key file that cannot be read, is accessible to
+// its group or other users, or contains an entry that could never match over the wire
 // contributes no keys, the reason is logged, and the LAN stays closed. Keys are
 // held in memory only as SHA-256 digests and are compared in constant time; a
 // rejected credential is logged as a short digest fingerprint, never as itself.
@@ -264,8 +264,8 @@ func (g *Gate) enabledLocked() bool {
 // enabled/disabled state and the key set a request is judged against cannot
 // change between two calls. The allowlist is checked before the credential,
 // so a caller outside it learns nothing about whether its key is valid. A
-// preflight is judged like any other request. Authorize does not write to the response; the proxy does, in
-// its own error format.
+// preflight is judged like any other request. Authorize does not write to the
+// response; the proxy does, in its own error format.
 func (g *Gate) Authorize(r *http.Request) Decision {
 	g.mu.Lock()
 	g.refreshLocked()

services/shared/ingressauth/owner_unix.go

@@ -35,7 +35,7 @@ func checkKeyFileAccessAs(info fs.FileInfo, euid int) error {
 		return fmt.Errorf("owned by uid %d, not by the proxy's user (uid %d)", uid, euid)
 	}
 	if perm := info.Mode().Perm(); perm&0o077 != 0 {
-		return fmt.Errorf("permissions %04o allow other users to read it; chmod 600", perm)
+		return fmt.Errorf("permissions %04o grant access to its group or other users; chmod 600, or supply the key through NVPAIR_PROXY_API_KEYS", perm)
 	}
 	return nil
 }