@replayio-app-building/netlify-recorder 0.15.2 → 0.15.4

package/README.md

@@ -155,6 +155,79 @@ const { status, recordingId } = await res.json();
 // recordingId: string | null
 ```
 
+### 4. Access control with secrets
+
+You can restrict access to captured requests by setting a `secret` string. When a secret is set, the request is only accessible via API calls that provide the same secret value. This lets each app isolate its requests from other apps sharing the same Netlify Recorder service.
+
+#### Setting a secret
+
+Pass `secret` in the options when wrapping your handler:
+
+```typescript
+export default createRecordingRequestHandler(
+  async (req) => {
+    const result = await myBusinessLogic();
+    return { statusCode: 200, body: JSON.stringify(result) };
+  },
+  {
+    callbacks: remoteCallbacks(RECORDER_URL),
+    handlerPath: "netlify/functions/my-handler",
+    secret: process.env.NETLIFY_RECORDER_SECRET,
+  }
+);
+```
+
+#### Listing requests by secret
+
+Use the `list-by-secret` endpoint to retrieve all requests associated with a secret, with optional filtering by status, handler path, and time range:
+
+```typescript
+const res = await fetch(
+  `${RECORDER_URL}/api/list-by-secret?secret=${secret}&status=recorded&handlerPath=netlify/functions/my-handler&after=2025-01-01T00:00:00Z&before=2025-12-31T23:59:59Z`
+);
+const { rows, total, page, limit } = await res.json();
+```
+
+Query parameters:
+
+| Parameter | Description |
+|---|---|
+| `secret` | **(required)** The secret string used when creating the requests |
+| `status` | Filter by status: `captured`, `queued`, `processing`, `recorded`, `failed` |
+| `handlerPath` | Filter by handler path (exact match) |
+| `after` | Only include requests created at or after this ISO timestamp |
+| `before` | Only include requests created at or before this ISO timestamp |
+| `page` | Page number (default 1) |
+| `limit` | Page size (default 20, max 100) |
+
+#### Checking request status with a secret
+
+When a request was created with a secret, you must include the secret when polling its status:
+
+```typescript
+const res = await fetch(
+  `${RECORDER_URL}/api/get-request?requestId=${requestId}&secret=${secret}`
+);
+```
+
+Requests created without a secret remain accessible without one (backward compatible).
+
+#### Managing your secret
+
+Store your secret as a `NETLIFY_RECORDER_SECRET` environment variable. To keep it secure:
+
+1. **Netlify site environment:** Add `NETLIFY_RECORDER_SECRET` in your Netlify site's environment variables (Site settings → Environment variables). This makes it available to all deployed functions.
+
+2. **Branch-level secret** (for CI/development): If you're using the Netlify Recorder agent infrastructure, store the secret as a branch secret so deploy scripts and background agents can access it:
+
+   ```bash
+   set-branch-secret NETLIFY_RECORDER_SECRET "your-secret-value"
+   ```
+
+3. **Local development:** Add `NETLIFY_RECORDER_SECRET` to your `.env` file (make sure `.env` is in `.gitignore`).
+
+Use a strong random string (e.g. `openssl rand -base64 32`) and rotate it if compromised. All requests created under the old secret remain accessible only with the old secret value — there is no migration mechanism, so plan rotations during low-traffic windows.
+
 ---
 
 ## Option B: Self-Hosted
@@ -305,6 +378,90 @@ 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.
+
+### Setup
+
+#### 1. Create the audit log table
+
+Call `databaseAuditEnsureLogTable` once during schema initialization. This creates the `audit_log` table, its indexes, and a reusable PL/pgSQL trigger function:
+
+```typescript
+import { databaseAuditEnsureLogTable } from "@replayio-app-building/netlify-recorder";
+
+await databaseAuditEnsureLogTable(sql);
+```
+
+#### 2. Monitor tables
+
+For each table you want to audit, call `databaseAuditMonitorTable`. This attaches a trigger that logs every INSERT, UPDATE, and DELETE:
+
+```typescript
+import { databaseAuditMonitorTable } from "@replayio-app-building/netlify-recorder";
+
+await databaseAuditMonitorTable(sql, "users");
+await databaseAuditMonitorTable(sql, "orders");
+```
+
+#### 3. Use audited SQL 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:
+
+```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})`;
+
+    return { statusCode: 200, body: "OK" };
+  },
+  {
+    callbacks: remoteCallbacks(RECORDER_URL),
+    handlerPath: "netlify/functions/create-order",
+  }
+);
+```
+
+#### 4. Query the audit log
+
+Use `databaseAuditDumpLogTable` to retrieve all audit entries (ordered by most recent first):
+
+```typescript
+import { databaseAuditDumpLogTable } from "@replayio-app-building/netlify-recorder";
+
+const entries = await databaseAuditDumpLogTable(sql);
+```
+
+Each entry contains:
+
+| Field | Description |
+|---|---|
+| `table_name` | The table where the change occurred |
+| `record_id` | The `id` of the affected row |
+| `action` | `INSERT`, `UPDATE`, or `DELETE` |
+| `old_data` | Previous row data (UPDATE/DELETE only) |
+| `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_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.
+
+---
+
 ## API Reference
 
 ### `createRecordingRequestHandler(handler, options): Handler`
@@ -322,6 +479,7 @@ When `context.waitUntil` is not available (v1 handlers or missing context), the
 - `options.commitSha` — Override `COMMIT_SHA` env var
 - `options.branchName` — Override `BRANCH_NAME` env var
 - `options.repositoryUrl` — Override `REPLAY_REPOSITORY_URL` env var
+- `options.secret` — Optional secret string. When set, the stored request is only accessible via API calls that provide the same secret value.
 
 **Returns:** A wrapped handler function with the same signature.
 
@@ -359,6 +517,7 @@ Logs a `console.warn` when the total duration exceeds 2 seconds or when individu
 - `options.branchName` — Override `BRANCH_NAME` env var
 - `options.repositoryUrl` — Override `REPLAY_REPOSITORY_URL` env var
 - `options.requestId` — Pre-generated request ID (used by `createRecordingRequestHandler` in the `waitUntil` flow)
+- `options.secret` — Optional secret string. When set, the stored request is only accessible via API calls that provide the same secret value.
 
 ### `remoteCallbacks(serviceUrl): FinishRequestCallbacks`
 
@@ -386,6 +545,39 @@ Called inside a container running under `replay-node`. Downloads the captured da
 - `handlerPath` — Path to the handler module to execute
 - `requestInfo` — The original request info to replay
 
+### `databaseAuditEnsureLogTable(sql): Promise<void>`
+
+Creates the `audit_log` table, its indexes, and a reusable PL/pgSQL trigger function (`audit_trigger_function`). Call once during schema initialization.
+
+**Parameters:**
+- `sql` — A Neon SQL tagged-template function
+
+### `databaseAuditMonitorTable(sql, tableName): Promise<void>`
+
+Attaches a trigger to the specified table that logs INSERT, UPDATE, and DELETE operations to the `audit_log` table. Throws if `tableName` is `'audit_log'`.
+
+**Parameters:**
+- `sql` — A Neon SQL tagged-template function
+- `tableName` — Name of the table to monitor (must match `^[a-zA-Z_][a-zA-Z0-9_]*$`)
+
+### `databaseAuditDumpLogTable(sql): Promise<Record<string, unknown>[]>`
+
+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`)

package/dist/index.d.ts

@@ -111,6 +111,8 @@ interface FinishRequestCallbacks {
         handlerPath: string;
         /** Pre-generated request ID. Use as the row ID when provided. */
         requestId?: string;
+        /** Optional secret that restricts access to this request. */
+        secret?: string;
     }) => Promise<string>;
 }
 /**
@@ -217,6 +219,11 @@ interface FinishRequestOptions {
      * the response is returned before `finishRequest` runs.
      */
     requestId?: string;
+    /**
+     * Optional secret string. When set, the stored request is only
+     * accessible via API calls that provide the same secret value.
+     */
+    secret?: string;
 }
 /**
  * Called at the end of the handler execution.

package/dist/index.js

@@ -126,6 +126,10 @@ function installNetworkInterceptor(mode, calls) {
 function installEnvironmentInterceptor(mode, reads) {
   const originalEnv = process.env;
   if (mode === "capture") {
+    const now = Date.now();
+    for (const key of Object.keys(originalEnv)) {
+      reads.push({ key, value: originalEnv[key], timestamp: now });
+    }
     process.env = new Proxy(originalEnv, {
       get(target, prop) {
         const value = target[prop];
@@ -454,7 +458,8 @@ async function finishRequest(requestContext, callbacks, response, options) {
     branchName,
     repositoryUrl,
     handlerPath,
-    requestId: options?.requestId
+    requestId: options?.requestId,
+    secret: options?.secret
   });
   const storeDuration = Date.now() - storeStart;
   if (storeDuration > SLOW_STEP_THRESHOLD_MS) {
@@ -560,7 +565,8 @@ function remoteCallbacks(serviceUrl) {
             commitSha: metadata.commitSha,
             branchName: metadata.branchName,
             repositoryUrl: metadata.repositoryUrl,
-            requestId: metadata.requestId
+            requestId: metadata.requestId,
+            secret: metadata.secret
           })
         }
       );
@@ -862,6 +868,16 @@ async function createRequestRecording(blobUrlOrData, handlerPath, requestInfo) {
     };
     g.File = FileShim;
   }
+  if (typeof g.crypto === "undefined") {
+    try {
+      const nodeCrypto = __require("crypto");
+      g.crypto = {
+        randomUUID: () => nodeCrypto.randomUUID(),
+        getRandomValues: (buf) => nodeCrypto.getRandomValues(buf)
+      };
+    } catch {
+    }
+  }
   if (typeof g.Headers === "undefined") {
     const HeadersShim = class Headers {
       _map;

package/package.json

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