@replayio-app-building/netlify-recorder 0.15.5 → 0.15.7

package/README.md

@@ -31,8 +31,9 @@ The Netlify Recorder app (`https://netlify-recorder-bm4wmw.netlify.app`) provide
 | `REPLAY_REPOSITORY_URL` | Your app's git repository URL (e.g. `https://github.com/org/repo.git`) | Set in your deploy script or Netlify site settings |
 | `COMMIT_SHA` | The git commit hash of the deployed code | Set in your deploy script via `git rev-parse HEAD` |
 | `BRANCH_NAME` | The git branch of the deployed code | Set in your deploy script via `git rev-parse --abbrev-ref HEAD` |
+| `NETLIFY_RECORDER_SECRET` | Secret string for access control — restricts who can view and act on your captured requests | Set in Netlify site environment variables or via `set-branch-secret` |
 
-**These are required.** `finishRequest` will throw an error if any are missing. Your deploy script should resolve them from git and set them on the Netlify site before deploying. Example:
+The first three are **required** — `finishRequest` will throw an error if any are missing. `NETLIFY_RECORDER_SECRET` is strongly recommended to prevent other apps from accessing your captured request data. Your deploy script should resolve the git values and set them on the Netlify site before deploying. Example:
 
 ```typescript
 // In your deploy script:
@@ -46,7 +47,7 @@ const repositoryUrl = execSync("git remote get-url origin", { encoding: "utf-8"
 
 ### 2. Wrap your Netlify function
 
-Use `createRecordingRequestHandler` with `remoteCallbacks()` to wrap your handler with automatic request capture.
+Use `createRecordingRequestHandler` with `remoteCallbacks()` to wrap your handler with automatic request capture. Set `secret` to restrict access to captured requests — only API calls providing the same secret can view or act on them.
 
 **v1 handler** (Netlify Functions v1 — `event` with `httpMethod`, `path`, etc.):
 
@@ -71,6 +72,7 @@ const handler = createRecordingRequestHandler(
   {
     callbacks: remoteCallbacks(RECORDER_URL),
     handlerPath: "netlify/functions/my-handler",
+    secret: process.env.NETLIFY_RECORDER_SECRET,
   }
 );
 
@@ -102,6 +104,7 @@ export default createRecordingRequestHandler(
   {
     callbacks: remoteCallbacks(RECORDER_URL),
     handlerPath: "netlify/functions/my-handler",
+    secret: process.env.NETLIFY_RECORDER_SECRET,
   }
 );
 ```
@@ -262,6 +265,7 @@ const handler = createRecordingRequestHandler(
     };
   },
   {
+    secret: process.env.NETLIFY_RECORDER_SECRET,
     callbacks: {
       uploadBlob: async (data) => {
         // Upload the JSON string to your blob storage (S3, R2, etc.)
@@ -272,10 +276,10 @@ const handler = createRecordingRequestHandler(
         const { url } = await res.json();
         return url;
       },
-      storeRequestData: async ({ blobUrl, commitSha, branchName, repositoryUrl, handlerPath }) => {
+      storeRequestData: async ({ blobUrl, commitSha, branchName, repositoryUrl, handlerPath, secret }) => {
         const [row] = await sql`
-          INSERT INTO requests (blob_url, commit_sha, branch_name, repository_url, handler_path, status)
-          VALUES (${blobUrl}, ${commitSha}, ${branchName}, ${repositoryUrl}, ${handlerPath}, 'captured')
+          INSERT INTO requests (blob_url, commit_sha, branch_name, repository_url, handler_path, secret, status)
+          VALUES (${blobUrl}, ${commitSha}, ${branchName}, ${repositoryUrl}, ${handlerPath}, ${secret}, 'captured')
           RETURNING id
         `;
         return row.id;
@@ -297,12 +301,15 @@ CREATE TABLE IF NOT EXISTS requests (
   branch_name TEXT,
   repository_url TEXT,
   handler_path TEXT,
+  secret TEXT,
   recording_id TEXT,
   status TEXT NOT NULL DEFAULT 'captured'
     CHECK (status IN ('captured', 'processing', 'recorded', 'failed')),
   created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
   updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
 );
+
+CREATE INDEX IF NOT EXISTS idx_requests_secret ON requests (secret) WHERE secret IS NOT NULL;
 ```
 
 ### 4. Create a background function to produce recordings
@@ -386,7 +393,7 @@ Self-hosted recording requires these environment variables:
 
 ## Audit Log Support
 
-The package includes helpers that automatically track database mutations (INSERT, UPDATE, DELETE) in an `audit_log` table and link each change to the Replay request that caused it. This makes it easy to trace exactly which incoming request triggered a given database change.
+The package automatically tracks database mutations (INSERT, UPDATE, DELETE) in an `audit_log` table and links each change to the Replay request that caused it. When your handler is wrapped with `createRecordingRequestHandler`, all Neon SQL queries are automatically tagged with the request ID — no changes to your SQL code required.
 
 ### Setup
 
@@ -411,29 +418,26 @@ await databaseAuditMonitorTable(sql, "users");
 await databaseAuditMonitorTable(sql, "orders");
 ```
 
-#### 3. Use audited SQL in your handlers
+#### 3. Use SQL normally in your handlers
 
-Wrap your Neon SQL function with `createAuditedSql` inside handlers that are wrapped with `createRecordingRequestHandler`. This ensures each audit log entry is stamped with the current Replay request ID and a per-request call index:
+No special SQL wrapper is needed. Any Neon SQL query inside a handler wrapped with `createRecordingRequestHandler` is automatically tagged with the replay request ID:
 
 ```typescript
 import {
   createRecordingRequestHandler,
   remoteCallbacks,
-  createAuditedSql,
 } from "@replayio-app-building/netlify-recorder";
 
 export default createRecordingRequestHandler(
   async (req) => {
-    const auditedSql = createAuditedSql(sql);
-    // Queries through auditedSql automatically tag audit_log rows
-    // with the replay request ID — no extra code needed.
-    await auditedSql`INSERT INTO orders (product, qty) VALUES (${product}, ${qty})`;
+    await sql`INSERT INTO orders (product, qty) VALUES (${product}, ${qty})`;
 
     return { statusCode: 200, body: "OK" };
   },
   {
     callbacks: remoteCallbacks(RECORDER_URL),
     handlerPath: "netlify/functions/create-order",
+    secret: process.env.NETLIFY_RECORDER_SECRET,
   }
 );
 ```
@@ -459,12 +463,12 @@ Each entry contains:
 | `new_data` | New row data (INSERT/UPDATE only) |
 | `changed_fields` | Array of column names that changed (UPDATE only) |
 | `performed_at` | Timestamp of the change |
-| `replay_request_id` | The Replay request ID that caused the change (when using `createAuditedSql`) |
+| `replay_request_id` | The Replay request ID that caused the change |
 | `replay_request_call_index` | The sequential query index within the request |
 
 ### How it works
 
-`createAuditedSql` wraps each query in a transaction that first calls `SET LOCAL` to inject the current request ID and call index into PostgreSQL session variables. The trigger function reads these via `current_setting()` and stamps audit rows atomically — no separate UPDATE required. If no request context is available (e.g. queries outside a handler), the query executes normally without audit metadata.
+The network interceptor detects Neon SQL HTTP requests (which use `fetch` internally) and automatically wraps each query in a transaction with `SET LOCAL` statements that inject the current request ID and call index. The PostgreSQL trigger function reads these via `current_setting()` and stamps audit rows atomically. Outside a handler context, queries execute normally without audit metadata.
 
 ---
 
@@ -573,17 +577,6 @@ Returns all rows from the `audit_log` table, ordered by `performed_at` DESC.
 **Parameters:**
 - `sql` — A Neon SQL tagged-template function
 
-### `createAuditedSql(sql): SqlFunction`
-
-Wraps a Neon SQL tagged-template function so that each query runs inside a transaction that injects the current Replay request ID and call index via `SET LOCAL`. The audit trigger reads these values and stamps audit rows automatically.
-
-Falls back to non-audited execution when no request context is active or if the transaction fails.
-
-**Parameters:**
-- `sql` — A Neon SQL tagged-template function (must have a `.transaction()` method, as provided by the Neon HTTP driver)
-
-**Returns:** A wrapped SQL function with the same tagged-template interface.
-
 ## Environment Variables
 
 ### Required for all setups (read by `finishRequest`)
@@ -595,6 +588,7 @@ These must be set on your Netlify site. Your deploy script should resolve them f
 | `COMMIT_SHA` | Git commit hash of the deployed code | `git rev-parse HEAD` |
 | `BRANCH_NAME` | Git branch of the deployed code | `git rev-parse --abbrev-ref HEAD` |
 | `REPLAY_REPOSITORY_URL` | Git repository URL (no embedded credentials) | `git remote get-url origin` (strip tokens) |
+| `NETLIFY_RECORDER_SECRET` | Secret for access control (strongly recommended) | `openssl rand -base64 32` — store in Netlify site env vars |
 
 ### Required for self-hosted recording (Option B)
 

package/dist/index.d.ts

@@ -448,27 +448,7 @@ declare function databaseAuditMonitorTable(sql: SqlFunction, tableName: string):
  * Returns all rows from the `audit_log` table, ordered by `performed_at` DESC.
  */
 declare function databaseAuditDumpLogTable(sql: SqlFunction): Promise<Record<string, unknown>[]>;
-/**
- * Wraps a Neon SQL tagged-template function so that each query runs
- * inside a transaction that first calls `set_config()` to inject the
- * current request ID and call index. The `audit_trigger_function`
- * reads these via `current_setting()` and stamps audit rows atomically
- * — no separate UPDATE required.
- *
- * Requires the Neon HTTP driver's `.transaction()` method so that
- * `set_config` and the user's query share one transaction.
- *
- * @example
- * ```ts
- * import { createAuditedSql } from "@replayio-app-building/netlify-recorder";
- *
- * const sql = createAuditedSql(getSql());
- * await sql`INSERT INTO haikus (text) VALUES (${haiku})`;
- * // audit_log row created by the trigger already has the request ID
- * ```
- */
-declare function createAuditedSql(sql: SqlFunction): SqlFunction;
 
 declare function getCurrentRequestId(): string | null;
 
-export { type BlobData, type CapturedData, type ContainerInfraConfig, type CreateRecordingRequestHandlerOptions, type EnsureRecordingOptions, type EnvRead, type FinishRequestCallbacks, type FinishRequestOptions, type HandlerResponse$1 as HandlerResponse, type NetlifyEvent, type NetlifyV2Request, type NetworkCall, type RecordingResult, type RequestContext, type RequestInfo, type SpawnRecordingContainerOptions, createAuditedSql, createRecordingRequestHandler, createRequestRecording, databaseAuditDumpLogTable, databaseAuditEnsureLogTable, databaseAuditMonitorTable, ensureRequestRecording, finishRequest, getCurrentRequestId, readInfraConfigFromEnv, redactBlobData, remoteCallbacks, spawnRecordingContainer, startRequest };
+export { type BlobData, type CapturedData, type ContainerInfraConfig, type CreateRecordingRequestHandlerOptions, type EnsureRecordingOptions, type EnvRead, type FinishRequestCallbacks, type FinishRequestOptions, type HandlerResponse$1 as HandlerResponse, type NetlifyEvent, type NetlifyV2Request, type NetworkCall, type RecordingResult, type RequestContext, type RequestInfo, type SpawnRecordingContainerOptions, createRecordingRequestHandler, createRequestRecording, databaseAuditDumpLogTable, databaseAuditEnsureLogTable, databaseAuditMonitorTable, ensureRequestRecording, finishRequest, getCurrentRequestId, readInfraConfigFromEnv, redactBlobData, remoteCallbacks, spawnRecordingContainer, startRequest };

package/dist/index.js

@@ -5,7 +5,41 @@ var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require
   throw Error('Dynamic require of "' + x + '" is not supported');
 });
 
+// src/requestState.ts
+var _currentRequestId = null;
+var _callIndex = 0;
+function setCurrentRequestId(id) {
+  _currentRequestId = id;
+  _callIndex = 0;
+}
+function getCurrentRequestId() {
+  return _currentRequestId;
+}
+function incrementCallIndex() {
+  return ++_callIndex;
+}
+
 // src/interceptors/network.ts
+function isNeonQuery(obj) {
+  return typeof obj === "object" && obj !== null && "query" in obj && "params" in obj;
+}
+function isNeonSqlRequest(url, body) {
+  if (!body) return false;
+  try {
+    const u = new URL(url);
+    if (!u.pathname.endsWith("/sql")) return false;
+    const parsed = JSON.parse(body);
+    return isNeonQuery(parsed) || Array.isArray(parsed) && parsed.length > 0 && isNeonQuery(parsed[0]);
+  } catch {
+    return false;
+  }
+}
+function buildSetConfigQueries(requestId, callIndex) {
+  return [
+    { query: "SELECT set_config('app.replay_request_id', $1, true)", params: [requestId] },
+    { query: "SELECT set_config('app.replay_call_index', $1, true)", params: [String(callIndex)] }
+  ];
+}
 function installNetworkInterceptor(mode, calls) {
   const originalFetch = globalThis.fetch;
   const consumed = /* @__PURE__ */ new Set();
@@ -20,6 +54,20 @@ function installNetworkInterceptor(mode, calls) {
         });
       }
       const requestBody = typeof init?.body === "string" ? init.body : void 0;
+      const requestId = getCurrentRequestId();
+      if (requestId && method.toUpperCase() === "POST" && isNeonSqlRequest(url, requestBody)) {
+        return await handleNeonSqlRequest(
+          originalFetch,
+          input,
+          init,
+          url,
+          method,
+          requestHeaders,
+          requestBody,
+          requestId,
+          calls
+        );
+      }
       const response = await originalFetch(input, init);
       const responseBody = await response.clone().text();
       const responseHeaders = {};
@@ -121,6 +169,50 @@ function installNetworkInterceptor(mode, calls) {
     }
   };
 }
+async function handleNeonSqlRequest(originalFetch, input, init, url, method, requestHeaders, requestBody, requestId, calls) {
+  const parsed = JSON.parse(requestBody);
+  const wasTransaction = Array.isArray(parsed);
+  const callIndex = incrementCallIndex();
+  const setConfigs = buildSetConfigQueries(requestId, callIndex);
+  const txBody = wasTransaction ? [...setConfigs, ...parsed] : [...setConfigs, parsed];
+  const modifiedInit = {
+    ...init,
+    body: JSON.stringify(txBody)
+  };
+  const response = await originalFetch(input, modifiedInit);
+  const rawBody = await response.clone().text();
+  const responseHeaders = {};
+  response.headers.forEach((v, k) => {
+    responseHeaders[k] = v;
+  });
+  let recordedBody = rawBody;
+  if (response.ok) {
+    try {
+      const json = JSON.parse(rawBody);
+      if (json.results && Array.isArray(json.results)) {
+        const stripped = json.results.slice(setConfigs.length);
+        const unwrapped = wasTransaction ? { results: stripped } : stripped[0] ?? json;
+        recordedBody = JSON.stringify(unwrapped);
+      }
+    } catch {
+    }
+  }
+  calls.push({
+    url,
+    method,
+    requestHeaders,
+    requestBody,
+    responseStatus: response.status,
+    responseHeaders,
+    responseBody: recordedBody,
+    timestamp: Date.now()
+  });
+  return new Response(recordedBody, {
+    status: response.status,
+    statusText: response.statusText,
+    headers: responseHeaders
+  });
+}
 
 // src/interceptors/environment.ts
 function installEnvironmentInterceptor(mode, reads) {
@@ -484,17 +576,6 @@ async function finishRequest(requestContext, callbacks, response, options) {
 
 // src/createRecordingRequestHandler.ts
 import crypto from "crypto";
-
-// src/requestState.ts
-var _currentRequestId = null;
-function setCurrentRequestId(id) {
-  _currentRequestId = id;
-}
-function getCurrentRequestId() {
-  return _currentRequestId;
-}
-
-// src/createRecordingRequestHandler.ts
 function createRecordingRequestHandler(handler, options) {
   return async (event, context) => {
     const requestId = crypto.randomUUID();
@@ -1149,7 +1230,7 @@ async function databaseAuditEnsureLogTable(sql) {
       req_id TEXT;
       call_idx INTEGER;
     BEGIN
-      -- Read application context set via SET LOCAL by createAuditedSql
+      -- Read application context injected by the network interceptor
       req_id := COALESCE(current_setting('app.replay_request_id', true), '');
       IF req_id = '' THEN req_id := NULL; END IF;
 
@@ -1201,30 +1282,7 @@ async function databaseAuditDumpLogTable(sql) {
   const rows = await sql`SELECT * FROM audit_log ORDER BY performed_at DESC`;
   return rows;
 }
-function createAuditedSql(sql) {
-  let callIndex = 0;
-  const sqlWithTx = sql;
-  const auditedSql = async (strings, ...values) => {
-    const requestId = getCurrentRequestId();
-    callIndex++;
-    if (requestId && typeof sqlWithTx.transaction === "function") {
-      try {
-        const results = await sqlWithTx.transaction([
-          sql`SELECT set_config('app.replay_request_id', ${requestId}, true)`,
-          sql`SELECT set_config('app.replay_call_index', ${String(callIndex)}, true)`,
-          sql(strings, ...values)
-        ]);
-        return results[2];
-      } catch (err) {
-        console.warn("netlify-recorder: audited transaction failed, falling back:", err);
-      }
-    }
-    return await sql(strings, ...values);
-  };
-  return auditedSql;
-}
 export {
-  createAuditedSql,
   createRecordingRequestHandler,
   createRequestRecording,
   databaseAuditDumpLogTable,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@replayio-app-building/netlify-recorder",
-  "version": "0.15.5",
+  "version": "0.15.7",
   "description": "Capture and replay Netlify function executions as Replay recordings",
   "type": "module",
   "exports": {