fix(audit): harden native lab gates and persistence

Author: dwgx

docs/audits/AUDIT_2026-06-06.md

@@ -0,0 +1,68 @@
+# Audit 2026-06-06
+
+Scope: v2.0.135 baseline, open GitHub issues, VPS deployment state, native bridge protocol notes, release workflow, dashboard performance, and HTTP ingress behavior.
+
+## Baseline
+
+- Local HEAD before this audit: v2.0.135 (`17a8b4a`), working tree clean.
+- VPS was already running v2.0.135 and `/health` reported the commit after the prior deployment fix.
+- Open issue clusters: upstream provider deadline around 236-243s, tool-call stability, WebSearch/WebFetch protocol work, SWE-1.6 special-agent routing, and dashboard large-list performance.
+- One security subagent failed with a remote 429, so security findings here are from the main-thread read-through plus the successful protocol/performance/release subagents.
+
+## Findings
+
+### High: release metadata was not injected into GHCR images
+
+`Dockerfile` accepts `BUILD_VERSION`, `BUILD_COMMIT`, `BUILD_COMMIT_MESSAGE`, `BUILD_COMMIT_DATE`, and `BUILD_BRANCH`, and `/health` reads the exported `WINDSURFAPI_BUILD_*` env. The tag release workflow did not pass those build args. Because `.dockerignore` excludes `.git`, release containers had no reliable source for `/health.commit`; Docker labels could still contain a revision, but `/health` could not read labels.
+
+Status in this audit: blocked by the current GitHub token, which has `repo` but not `workflow` scope. GitHub rejects any push that modifies `.github/workflows/release.yml` without `workflow` scope. Keep this as the first follow-up once a workflow-scoped token is available.
+
+### High: WebFetch/Read native bridge is still lab-only
+
+Confirmed facts:
+
+- Native bridge defaults remain narrow. Read/WebFetch/WebSearch are mapped but not in the default mature native set.
+- WebFetch direct API that returns URL content has not been found. The observed official path is LS `HandleCascadeUserInteraction` for `read_url_content` permission approval, followed by trajectory steps.
+- `read_url_content` completed output should come from `web_document` field 2. The top-level field 5 fallback was historical and is not confirmed for current official protocol.
+- Read wrapper `type=14 field=19` remains partially reversed. v2.0.131 stopped prompt text from being promoted as a path, but that does not make Read production-ready.
+
+Fix in this audit: WebFetch auto-approve now canonicalizes URL/origin and only accepts http(s) URLs without embedded credentials. `read_url_content` top-level field 5 fallback is now behind `WINDSURFAPI_NATIVE_TOOL_BRIDGE_READ_URL_LEGACY_SUMMARY=1`; default parsing only trusts `web_document`.
+
+Still not fixed by design: do not production-open Read/WebSearch/WebFetch by default. Continue gated canaries only.
+
+### Medium: oversized HTTP bodies were misclassified
+
+`readBody()` detected bodies over 10 MB, but route-level JSON parse catches returned `400 Invalid JSON` for chat/responses/messages. That misled clients and operators.
+
+Fix in this audit: `readBody()` now preserves a 413-class error and routes return protocol-shaped 413 payloads.
+
+### Medium: atomic JSON temp files could race across processes
+
+Several JSON persisters used one fixed sibling temp path such as `accounts.json.tmp` or `config.json.tmp`. Concurrent writers in separate processes could collide on the same temp file; on Windows, replacing the final target can also briefly fail while another test/process has the file open.
+
+Fix in this audit: atomic JSON writers now use unique sibling temp names and retry short-lived `EPERM`/`EBUSY` rename failures before surfacing the error.
+
+### Medium: dashboard account pages do full heavy-list rendering
+
+`GET /dashboard/api/accounts` returns all accounts with heavy fields such as capabilities, credits, available models, tier models, user status, and LS admission. The front end renders all account rows at once; the anomaly page also full-renders and polls every 30 seconds. This matches issue #168.
+
+Not fixed in this audit: this needs a separate dashboard pagination/summary endpoint slice. It is larger than the release/protocol hardening changes and should not be mixed into the same patch.
+
+### Medium: stream and cache memory pressure remain bounded by count, not bytes
+
+Conversation pool and response cache have item limits and TTLs. Response cache does not have a byte cap, and streaming accumulates text for downstream usage/cache logic. SSE writes do not wait for `drain` on slow clients.
+
+Not fixed in this audit: recommended follow-up is byte caps plus backpressure-aware SSE writes.
+
+## Non-Bugs / External Limits
+
+- The 236-243s `context deadline exceeded` issue is a Windsurf upstream provider/Cascade stream window. Local `CASCADE_MAX_WAIT_MS` is not the limiting factor.
+- SWE-1.6 should not be treated as a normal catalog or entitlement bug. It should continue through the Devin/ACP special-agent POC path.
+- Trial/free rate limits, entitlement misses, and IP-level cooldowns are upstream capacity controls; local routing can surface them clearly but cannot create upstream quota.
+
+## Next Execution Plan
+
+1. Release and deploy the current hardening patch, then smoke VPS.
+2. With a token that has `workflow` scope, apply the release workflow metadata/test-gate fix.
+3. Next patch: dashboard account pagination/lightweight summary endpoint for #168.
+4. Next protocol work: continue raw-child traces for `type=14 field=19` Read wrapper and WebSearch/WebFetch traces, but keep production native defaults narrow.

docs/releases/RELEASE_NOTES_2.0.136.md

@@ -0,0 +1,19 @@
+# v2.0.136 - audit hardening
+
+## What changed
+
+- Oversized HTTP request bodies now return protocol-shaped `413 Request body too large` errors instead of being misclassified as `Invalid JSON`.
+- WebFetch lab auto-approve now canonicalizes URL/origin allowlist entries and rejects non-http(s), malformed, or credential-bearing URLs.
+- `read_url_content` no longer trusts the unconfirmed top-level field 5 summary by default; legacy fallback requires `WINDSURFAPI_NATIVE_TOOL_BRIDGE_READ_URL_LEGACY_SUMMARY=1`.
+- Atomic JSON writes now use unique temporary filenames and retry short-lived Windows rename locks, including `accounts.json`.
+- Added `docs/audits/AUDIT_2026-06-06.md` with the audit baseline, findings, fixed items, and remaining follow-ups.
+
+## Notes
+
+- Read/WebSearch/WebFetch remain lab-only native bridge surfaces. This release tightens canary behavior; it does not production-open those tools.
+- Release workflow metadata/test-gate hardening is documented in the audit, but was not included in this release because the current GitHub token lacks `workflow` scope.
+- Dashboard account pagination for #168 is the next recommended implementation slice.
+
+## Validation
+
+- `node --test test/*.test.js` -> 1070/1070 passing.

package.json

@@ -1,6 +1,6 @@
 {
   "name": "windsurf-api",
-  "version": "2.0.135",
+  "version": "2.0.136",
   "description": "Windsurf to OpenAI + Anthropic compatible API proxy. Turns Windsurf's 107 AI models (Claude, GPT, Gemini, DeepSeek, Grok, Qwen, Kimi, GLM, SWE) into dual-protocol API endpoints. Zero npm deps.",
   "type": "module",
   "main": "src/index.js",

src/auth.js

@@ -13,8 +13,9 @@
 import { createHash, randomUUID, timingSafeEqual } from 'crypto';
 import { isStickyEnabled, getStickyBinding, setStickyBinding, clearStickyBinding } from './account/sticky-session.js';
 import { isExperimentalEnabled } from './runtime-config.js';
-import { readFileSync, writeFileSync, existsSync, renameSync, unlinkSync, readdirSync } from 'fs';
+import { readFileSync, writeFileSync, existsSync, unlinkSync, readdirSync } from 'fs';
 import { config, log } from './config.js';
+import { renameSyncWithRetry } from './fs-atomic.js';
 import { getEffectiveProxy } from './dashboard/proxy-config.js';
 import { getTierModels, getModelKeysByEnum, MODELS, registerDiscoveredFreeModel } from './models.js';
 import { getLsAdmissionStatus, getLsMaintenanceRequests } from './langserver.js';
@@ -247,13 +248,14 @@ function _serializeAccounts() {
 function saveAccounts() {
   if (_saveInFlight) { _savePending = true; return; }
   _saveInFlight = true;
-  const tempFile = ACCOUNTS_FILE + '.tmp';
+  const tempFile = `${ACCOUNTS_FILE}.${process.pid}.${randomUUID().slice(0, 8)}.tmp`;
   try {
-    // Atomic write: write to .tmp then rename so a crash mid-write can't
-    // leave accounts.json truncated/corrupt. Node's renameSync is atomic
-    // on POSIX and replaces the target on Windows (fs.rename behavior).
+    // Atomic write: write to a unique sibling tmp then rename so a crash
+    // mid-write cannot leave accounts.json truncated/corrupt. The unique
+    // tmp also prevents concurrent test/process saves from racing on the
+    // same `${ACCOUNTS_FILE}.tmp` name.
     writeFileSync(tempFile, JSON.stringify(_serializeAccounts(), null, 2));
-    renameSync(tempFile, ACCOUNTS_FILE);
+    renameSyncWithRetry(tempFile, ACCOUNTS_FILE);
   } catch (e) {
     log.error('Failed to save accounts:', e.message);
     try { unlinkSync(tempFile); } catch {}
@@ -271,10 +273,10 @@ function saveAccounts() {
  * atomic.
  */
 export function saveAccountsSync() {
-  const tempFile = ACCOUNTS_FILE + '.shutdown.tmp';
+  const tempFile = `${ACCOUNTS_FILE}.${process.pid}.shutdown.tmp`;
   try {
     writeFileSync(tempFile, JSON.stringify(_serializeAccounts(), null, 2));
-    renameSync(tempFile, ACCOUNTS_FILE);
+    renameSyncWithRetry(tempFile, ACCOUNTS_FILE);
   } catch (e) {
     log.error('Shutdown: failed to flush accounts:', e.message);
     try { unlinkSync(tempFile); } catch {}
@@ -318,7 +320,7 @@ export function migrateReplicaAccountsTo({ sharedDir, accountsFile, logger = log
   const tempFile = accountsFile + '.migrate.tmp';
   try {
     writeFileSync(tempFile, JSON.stringify([...merged.values()], null, 2));
-    renameSync(tempFile, accountsFile);
+    renameSyncWithRetry(tempFile, accountsFile);
     logger.warn?.(`Migrated ${merged.size} account(s) from ${scanned} replica-* subdir(s) into ${accountsFile} (issue #67)`);
     return { migrated: merged.size, scanned, skipped: false };
   } catch (e) {

src/client.js

@@ -73,12 +73,38 @@ function csvSetEnv(name) {
     .filter(Boolean));
 }
 
-function isReadUrlAutoApproveAllowed(url, origin) {
+function canonicalWebUrl(value) {
+  const raw = String(value || '').trim();
+  if (!raw) return null;
+  let parsed;
+  try { parsed = new URL(raw); } catch { return null; }
+  if (parsed.protocol !== 'https:' && parsed.protocol !== 'http:') return null;
+  if (parsed.username || parsed.password) return null;
+  parsed.hash = '';
+  return {
+    origin: parsed.origin,
+    href: parsed.href.replace(/\/+$/, ''),
+  };
+}
+
+export function isReadUrlAutoApproveAllowed(url, origin) {
   if (process.env.WINDSURFAPI_NATIVE_TOOL_BRIDGE_WEBFETCH_AUTO_APPROVE !== '1') return false;
   const allow = csvSetEnv('WINDSURFAPI_NATIVE_TOOL_BRIDGE_WEBFETCH_AUTO_APPROVE_ORIGINS');
   if (!allow.size) return false;
-  const candidates = [origin, url].map(v => String(v || '').trim()).filter(Boolean);
-  return candidates.some(v => allow.has(v) || allow.has(v.replace(/\/+$/, '')));
+  const requestUrl = canonicalWebUrl(url);
+  if (!requestUrl) return false;
+  const originHint = canonicalWebUrl(origin)?.origin || '';
+  if (originHint && originHint !== requestUrl.origin) return false;
+  for (const entry of allow) {
+    const allowed = canonicalWebUrl(entry);
+    if (!allowed) continue;
+    if (allowed.href === allowed.origin) {
+      if (allowed.origin === requestUrl.origin) return true;
+      continue;
+    }
+    if (allowed.href === requestUrl.href) return true;
+  }
+  return false;
 }
 
 function isImageLikeBlock(part) {

src/fs-atomic.js

@@ -9,7 +9,7 @@
  * silently falls back to defaults — user loses every persisted
  * setting, model-access list, proxy config, etc.
  *
- * Pattern: write the new contents to a sibling `${target}.tmp` first,
+ * Pattern: write the new contents to a unique sibling `${target}.*.tmp` first,
  * then `rename(2)` it onto the target. rename is atomic on POSIX and
  * replaces an existing target on Windows (per Node's documented
  * fs.renameSync behavior). A crash between writeFileSync(tmp) and
@@ -25,13 +25,35 @@
  * because it has its own coalescing/_saveInFlight machinery).
  */
 
+import { randomUUID } from 'node:crypto';
 import { writeFileSync, renameSync, unlinkSync } from 'node:fs';
 
+const RETRYABLE_RENAME_CODES = new Set(['EPERM', 'EBUSY']);
+
+function sleepSync(ms) {
+  try {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+  } catch {}
+}
+
+export function renameSyncWithRetry(sourcePath, targetPath, { attempts = 6, baseDelayMs = 10 } = {}) {
+  const maxAttempts = Math.max(1, attempts | 0);
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    try {
+      renameSync(sourcePath, targetPath);
+      return;
+    } catch (err) {
+      if (!RETRYABLE_RENAME_CODES.has(err?.code) || attempt === maxAttempts) throw err;
+      sleepSync(baseDelayMs * attempt);
+    }
+  }
+}
+
 export function writeJsonAtomic(targetPath, value, { spaces = 2 } = {}) {
-  const tmp = `${targetPath}.tmp`;
+  const tmp = `${targetPath}.${process.pid}.${randomUUID().slice(0, 8)}.tmp`;
   try {
     writeFileSync(tmp, JSON.stringify(value, null, spaces));
-    renameSync(tmp, targetPath);
+    renameSyncWithRetry(tmp, targetPath);
   } catch (err) {
     try { unlinkSync(tmp); } catch {}
     throw err;

src/server.js

@@ -38,26 +38,60 @@ const VERSION_INFO = getVersionInfo();
 
 // 10 MB is way above any realistic chat-completions payload while still
 // bounding worst-case memory from a malicious/broken client.
-const MAX_BODY_SIZE = 10 * 1024 * 1024;
+export const MAX_BODY_SIZE = 10 * 1024 * 1024;
 
-function readBody(req) {
+export function readBody(req) {
   return new Promise((resolve, reject) => {
     const chunks = [];
     let size = 0;
+    let settled = false;
+    const fail = (err) => {
+      if (settled) return;
+      settled = true;
+      chunks.length = 0;
+      try { req.resume?.(); } catch {}
+      reject(err);
+    };
     req.on('data', c => {
+      if (settled) return;
       size += c.length;
       if (size > MAX_BODY_SIZE) {
-        req.destroy();
-        reject(Object.assign(new Error('Request body too large'), { statusCode: 413 }));
+        fail(Object.assign(new Error('Request body too large'), {
+          statusCode: 413,
+          code: 'ERR_REQUEST_BODY_TOO_LARGE',
+        }));
         return;
       }
       chunks.push(c);
     });
-    req.on('end', () => resolve(Buffer.concat(chunks).toString('utf-8')));
-    req.on('error', reject);
+    req.on('end', () => {
+      if (settled) return;
+      settled = true;
+      resolve(Buffer.concat(chunks).toString('utf-8'));
+    });
+    req.on('error', fail);
   });
 }
 
+export function bodyTooLargePayload(style = 'openai') {
+  if (style === 'dashboard') {
+    return { ok: false, error: 'ERR_REQUEST_BODY_TOO_LARGE', message: 'Request body too large' };
+  }
+  if (style === 'legacy') {
+    return { error: 'Request body too large' };
+  }
+  if (style === 'anthropic') {
+    return { type: 'error', error: { type: 'invalid_request_error', message: 'Request body too large' } };
+  }
+  return { error: { message: 'Request body too large', type: 'invalid_request' } };
+}
+
+function sendBodyTooLargeIfNeeded(res, err, style = 'openai') {
+  if (err?.statusCode !== 413 && err?.code !== 'ERR_REQUEST_BODY_TOO_LARGE') return false;
+  json(res, 413, bodyTooLargePayload(style));
+  return true;
+}
+
 export function extractToken(req) {
   // Anthropic SDK + OAI SDK compatibility: accept either header.
   const authHeader = String(req.headers['authorization'] || '').trim();
@@ -176,7 +210,9 @@ async function route(req, res) {
   if (path.startsWith('/dashboard/api/')) {
     let body = {};
     if (method === 'POST' || method === 'PUT' || method === 'PATCH') {
-      try { body = JSON.parse(await readBody(req)); } catch {}
+      try { body = JSON.parse(await readBody(req)); } catch (err) {
+        if (sendBodyTooLargeIfNeeded(res, err, 'dashboard')) return;
+      }
     }
     const subpath = path.slice('/dashboard/api'.length);
     return handleDashboardApi(method, subpath, body, req, res);
@@ -251,7 +287,8 @@ async function route(req, res) {
 
   if (path === '/auth/login' && method === 'POST') {
     let body;
-    try { body = JSON.parse(await readBody(req)); } catch {
+    try { body = JSON.parse(await readBody(req)); } catch (err) {
+      if (sendBodyTooLargeIfNeeded(res, err, 'legacy')) return;
       return json(res, 400, { error: 'Invalid JSON' });
     }
 
@@ -334,7 +371,8 @@ async function route(req, res) {
     }
 
     let body;
-    try { body = JSON.parse(await readBody(req)); } catch {
+    try { body = JSON.parse(await readBody(req)); } catch (err) {
+      if (sendBodyTooLargeIfNeeded(res, err, 'openai')) return;
       return json(res, 400, { error: { message: 'Invalid JSON', type: 'invalid_request' } });
     }
     if (!Array.isArray(body.messages)) {
@@ -392,7 +430,8 @@ async function route(req, res) {
     }
 
     let body;
-    try { body = JSON.parse(await readBody(req)); } catch {
+    try { body = JSON.parse(await readBody(req)); } catch (err) {
+      if (sendBodyTooLargeIfNeeded(res, err, 'openai')) return;
       return json(res, 400, { error: { message: 'Invalid JSON', type: 'invalid_request' } });
     }
     if (body.input == null) {
@@ -435,7 +474,8 @@ async function route(req, res) {
       return json(res, 503, { type: 'error', error: { type: 'api_error', message: 'No active accounts' } });
     }
     let body;
-    try { body = JSON.parse(await readBody(req)); } catch {
+    try { body = JSON.parse(await readBody(req)); } catch (err) {
+      if (sendBodyTooLargeIfNeeded(res, err, 'anthropic')) return;
       return json(res, 400, { type: 'error', error: { type: 'invalid_request_error', message: 'Invalid JSON' } });
     }
     if (!Array.isArray(body.messages) || body.messages.length === 0) {

src/windsurf.js

@@ -64,6 +64,10 @@ import {
 } from './proto.js';
 import { getSystemPrompts } from './runtime-config.js';
 
+function readUrlLegacySummaryFallbackEnabled() {
+  return process.env.WINDSURFAPI_NATIVE_TOOL_BRIDGE_READ_URL_LEGACY_SUMMARY === '1';
+}
+
 // ─── Enums ─────────────────────────────────────────────────
 
 export const SOURCE = {
@@ -1261,7 +1265,9 @@ export function parseTrajectorySteps(buf) {
           argumentsJson = JSON.stringify(args);
           const webDocument = getField(body, 2, 2);
           result = webDocument ? decodeKnowledgeBaseItemText(webDocument.value) : '';
-          if (!result) result = getField(body, 5, 2)?.value?.toString('utf8') || '';
+          if (!result && readUrlLegacySummaryFallbackEnabled()) {
+            result = getField(body, 5, 2)?.value?.toString('utf8') || '';
+          }
           if (!result && readUrlRequestedInteraction) continue;
         } else if (kind === 'search_web') {
           const args = {

test/audit-fixes.test.js

@@ -33,9 +33,10 @@ describe('writeJsonAtomic (audit fix #1: durable config writes)', () => {
       const target = join(dir, 'config.json');
       writeJsonAtomic(target, { hello: 'world', n: 1 });
       assert.deepEqual(JSON.parse(readFileSync(target, 'utf8')), { hello: 'world', n: 1 });
-      // The .tmp sibling must NOT exist after a successful write —
+      // Tmp siblings must NOT exist after a successful write —
       // otherwise we'd leak garbage into DATA_DIR every save.
-      assert.ok(!existsSync(`${target}.tmp`), '.tmp file should be removed after rename');
+      const leftover = readdirSync(dir).filter(f => f.endsWith('.tmp'));
+      assert.deepEqual(leftover, [], `expected no .tmp leftovers, got ${leftover.join(',')}`);
     } finally {
       rmSync(dir, { recursive: true, force: true });
     }