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

package/README.md

@@ -112,7 +112,7 @@ export default createRecordingRequestHandler(
 
 ### 2. Create recordings
 
-When you want to turn a captured request into a Replay recording, POST to the service's `create-recording` endpoint with the request ID:
+When you want to turn a captured request into a Replay recording, POST to the service's `create-recording` endpoint with the request ID. If the request was created with a secret, you must include it:
 
 ```typescript
 const response = await fetch(
@@ -122,6 +122,7 @@ const response = await fetch(
     headers: { "Content-Type": "application/json" },
     body: JSON.stringify({
       requestId,
+      secret,
       webhookUrl: "https://your-app.netlify.app/api/on-recording-complete", // optional
     }),
   }
@@ -144,17 +145,95 @@ On failure:
 
 ### 3. Check recording status
 
-You can poll the recording status at any time:
+You can poll the recording status at any time. If the request was created with a secret, you must include it:
 
 ```typescript
 const res = await fetch(
-  `${RECORDER_URL}/api/get-request?requestId=${requestId}`
+  `${RECORDER_URL}/api/get-request?requestId=${requestId}&secret=${secret}`
 );
 const { status, recordingId } = await res.json();
 // status: "captured" | "processing" | "recorded" | "failed"
 // recordingId: string | null
 ```
 
+Requests created with a secret return 403 if the secret is missing or incorrect.
+
+### 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 `requests` endpoint with a `secret` parameter to retrieve all requests associated with your secret, with optional filtering by status, handler path, and time range:
+
+```typescript
+const res = await fetch(
+  `${RECORDER_URL}/api/requests?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 |
+| `id` | Search by request ID prefix |
+| `status` | Filter by status: `captured`, `queued`, `processing`, `recorded`, `failed`, `all` |
+| `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) |
+
+Without a `secret` parameter, only requests created without a secret are returned.
+
+#### 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
@@ -406,6 +485,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.
 
@@ -443,6 +523,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`
 

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

@@ -458,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) {
@@ -564,7 +565,8 @@ function remoteCallbacks(serviceUrl) {
             commitSha: metadata.commitSha,
             branchName: metadata.branchName,
             repositoryUrl: metadata.repositoryUrl,
-            requestId: metadata.requestId
+            requestId: metadata.requestId,
+            secret: metadata.secret
           })
         }
       );

package/package.json

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