shorten holdback flush to 15ms and cover remaining holdback paths

Fragments that split a secret arrive within the same tick or a few ms, so a
15ms flush valve covers them the same as 100ms while keeping the worst-case
stall of a lookalike tail imperceptible.

New tests: callback fires when a whole chunk is withheld, bare end() flushes
withheld text, and a secret completed after the timed flush is still caught
via carry.

Author: theoephraim

packages/varlock-website/public/.well-known/ai-catalog.json

@@ -0,0 +1,69 @@
+{
+  "specVersion": "1.0",
+  "host": {
+    "displayName": "Varlock",
+    "identifier": "varlock.dev",
+    "url": "https://varlock.dev"
+  },
+  "entries": [
+    {
+      "identifier": "urn:ai:varlock.dev:mcp:docs",
+      "displayName": "Varlock docs MCP server",
+      "description": "Search and read the varlock documentation over MCP (streamable HTTP at /mcp, SSE at /sse). No authentication required.",
+      "type": "application/mcp-server+json",
+      "url": "https://varlock.dev/.well-known/mcp/server-card.json",
+      "endpoint": "https://docs.mcp.varlock.dev/mcp",
+      "representativeQueries": [
+        "How do I mark a variable as sensitive in .env.schema?",
+        "How do I run a command with varlock run?",
+        "How do I load secrets from 1Password with varlock?",
+        "How do I set up varlock with Next.js?"
+      ]
+    },
+    {
+      "identifier": "urn:ai:varlock.dev:docs:llms-txt",
+      "displayName": "Varlock documentation index (llms.txt)",
+      "description": "Entry point for agents: what varlock is, when to use it, install commands, and links to topic-specific documentation bundles.",
+      "type": "text/markdown",
+      "url": "https://varlock.dev/llms.txt",
+      "representativeQueries": [
+        "What is varlock and when should I use it?",
+        "How do I install the varlock CLI?"
+      ]
+    },
+    {
+      "identifier": "urn:ai:varlock.dev:docs:llms-full",
+      "displayName": "Varlock full documentation (llms-full.txt)",
+      "description": "Every varlock docs page concatenated into one markdown file.",
+      "type": "text/markdown",
+      "url": "https://varlock.dev/llms-full.txt",
+      "representativeQueries": [
+        "Reference for varlock .env.schema decorators",
+        "Which secret providers does varlock support?"
+      ]
+    },
+    {
+      "identifier": "urn:ai:varlock.dev:skills:index",
+      "displayName": "Varlock agent skills",
+      "description": "Agent Skills discovery index with SKILL.md files for using varlock, searching its docs, and verifying its discovery endpoints.",
+      "type": "application/json",
+      "url": "https://varlock.dev/.well-known/agent-skills/index.json",
+      "representativeQueries": [
+        "Install the varlock skill for my coding agent",
+        "How should an agent edit .env.schema safely?"
+      ]
+    },
+    {
+      "identifier": "urn:ai:varlock.dev:cli:varlock",
+      "displayName": "varlock CLI",
+      "description": "Command line tool for loading, validating, encrypting, and scanning .env files. Install with npx varlock init, brew install dmno-dev/tap/varlock, or the install.sh script.",
+      "type": "text/html",
+      "url": "https://varlock.dev/getting-started/installation/",
+      "representativeQueries": [
+        "Install varlock",
+        "Validate my .env file from the command line",
+        "Scan my repo for leaked secrets"
+      ]
+    }
+  ]
+}

packages/varlock-website/public/.well-known/mcp.json

@@ -0,0 +1,31 @@
+{
+  "$schema": "https://modelcontextprotocol.io/schemas/2025-03-26/server-card.json",
+  "serverInfo": {
+    "name": "Varlock docs MCP",
+    "version": "1.0.0",
+    "description": "Search and read the varlock documentation. No authentication required.",
+    "documentationUrl": "https://varlock.dev/guides/mcp/docs-mcp/"
+  },
+  "transports": [
+    {
+      "type": "streamable-http",
+      "endpoint": "https://docs.mcp.varlock.dev/mcp"
+    },
+    {
+      "type": "sse",
+      "endpoint": "https://docs.mcp.varlock.dev/sse"
+    }
+  ],
+  "capabilities": {
+    "tools": {
+      "listChanged": false
+    },
+    "resources": {
+      "subscribe": false,
+      "listChanged": false
+    },
+    "prompts": {
+      "listChanged": false
+    }
+  }
+}

packages/varlock-website/public/.well-known/mcp/server-cards.json

@@ -0,0 +1,35 @@
+{
+  "servers": [
+    {
+      "$schema": "https://modelcontextprotocol.io/schemas/2025-03-26/server-card.json",
+      "serverInfo": {
+        "name": "Varlock docs MCP",
+        "version": "1.0.0",
+        "description": "Search and read the varlock documentation. No authentication required.",
+        "documentationUrl": "https://varlock.dev/guides/mcp/docs-mcp/"
+      },
+      "transports": [
+        {
+          "type": "streamable-http",
+          "endpoint": "https://docs.mcp.varlock.dev/mcp"
+        },
+        {
+          "type": "sse",
+          "endpoint": "https://docs.mcp.varlock.dev/sse"
+        }
+      ],
+      "capabilities": {
+        "tools": {
+          "listChanged": false
+        },
+        "resources": {
+          "subscribe": false,
+          "listChanged": false
+        },
+        "prompts": {
+          "listChanged": false
+        }
+      }
+    }
+  ]
+}

packages/varlock-website/src/content/docs/guides/secrets.mdx

@@ -188,7 +188,7 @@ This works by patching:
 - **Node.js `ServerResponse`**: intercepts `write()` and `end()` calls, scanning text and JSON response bodies (including gzip-compressed responses)
 - **Global `Response` constructor**: intercepts the `Response` class used in edge runtimes (e.g., Cloudflare Workers), scanning bodies passed to the constructor and `Response.json()`
 
-Streamed responses are scanned across chunk boundaries, so a sensitive value that gets split between two writes is still detected. When the end of a chunk looks like the start of a sensitive value, that trailing text is held back for up to 100ms (or until the next chunk arrives) so the full value can be caught before any of it is sent.
+Streamed responses are scanned across chunk boundaries, so a sensitive value that gets split between two writes is still detected. When the end of a chunk looks like the start of a sensitive value, that trailing text is held back briefly (up to 15ms, or until the next chunk arrives) so the full value can be caught before any of it is sent.
 
 Our [framework integrations](/integrations/overview/) automatically apply the appropriate patches for your environment. For example, a Next.js integration will scan both server-rendered pages and API route responses.
 

packages/varlock/src/runtime/patch-server-response.ts

@@ -13,12 +13,15 @@ import { debug } from './lib/debug';
 const patchedKey = '_patchedByVarlock';
 
 /**
- * How long to hold back a possible partial secret before writing it out anyway. Chunks that
- * split a secret arrive back-to-back in practice, so this only fires when a response genuinely
- * pauses right after emitting something that looks like the start of a secret (e.g. SSE) -
- * without it, that trailing text would sit unsent until the next chunk or `end()`.
+ * How long to hold back a possible partial secret before writing it out anyway. This is a
+ * flush valve, not a detection window: chunks that split a secret arrive within the same tick
+ * or a few ms of each other (renderer buffer splits, piped upstream fragments), so a short
+ * timeout covers them while keeping the worst-case stall of a lookalike tail imperceptible.
+ * It only fires when a response genuinely pauses right after emitting something that looks
+ * like the start of a secret (e.g. an unframed SSE-style stream) - without it, that trailing
+ * text would sit unsent until the next chunk or `end()`.
  */
-const PENDING_FLUSH_TIMEOUT_MS = 100;
+const PENDING_FLUSH_TIMEOUT_MS = 15;
 
 /**
  * Returns a sync decompressor for a Content-Encoding value, or undefined if unsupported.

packages/varlock/src/runtime/test/patch-server-response.test.ts

@@ -223,6 +223,33 @@ describe('patched ServerResponse - sensitive values split across chunks', () =>
     expect(() => res.write(`<html>${head}`)).not.toThrow();
     expect(() => res.end('-but-not-really</html>')).not.toThrow();
   });
+
+  it('still detects the secret when its head was already flushed by the holdback timer', async () => {
+    const res = makeRes();
+    expect(() => res.write(`<html>leaked: ${head}`)).not.toThrow();
+    // wait past the holdback window so the timer flushes the withheld head, which
+    // moves it into `carry` - the completing chunk must still be caught there
+    await new Promise((resolve) => {
+      setTimeout(resolve, 60);
+    });
+    expect(() => res.write(`${tail}</html>`)).toThrow(/DETECTED LEAKED SENSITIVE CONFIG/);
+  });
+
+  it('reports success and fires the callback when a whole chunk is withheld', async () => {
+    const res = makeRes();
+    // the entire chunk is a possible secret prefix, so nothing goes out yet - but the
+    // caller must still see a normal successful write or streams piping into the
+    // response would stall waiting on the callback
+    let cbFired = false;
+    const returned = res.write(head, () => {
+      cbFired = true;
+    });
+    expect(returned).toBe(true);
+    await new Promise((resolve) => {
+      process.nextTick(resolve);
+    });
+    expect(cbFired).toBe(true);
+  });
 });
 
 /*
@@ -253,6 +280,11 @@ describe('patched ServerResponse - pass-through integrity', () => {
         res.write(buf.subarray(0, mid));
         res.write(buf.subarray(mid));
         res.end();
+      } else if (req.url === '/withheld-then-bare-end') {
+        // tail is withheld as a lookalike, and end() carries no chunk of its own -
+        // the withheld text must still be flushed as the final chunk
+        res.write(`<html>${SECRET.slice(0, 12)}`);
+        res.end();
       } else if (req.url === '/slow-lookalike') {
         // pauses right after a partial match, so the held-back text must still be flushed
         res.write(`<html>${SECRET.slice(0, 12)}`);
@@ -289,6 +321,11 @@ describe('patched ServerResponse - pass-through integrity', () => {
     expect(body).toBe(`<html>${multibyte}</html>`);
   });
 
+  it('delivers withheld text when end() carries no chunk', async () => {
+    const body = await (await fetch(`${baseUrl}/withheld-then-bare-end`)).text();
+    expect(body).toBe(`<html>${SECRET.slice(0, 12)}`);
+  });
+
   it('flushes withheld text without waiting for the response to end', async () => {
     const resp = await fetch(`${baseUrl}/slow-lookalike`);
     const reader = resp.body!.getReader();