@brunyee-studio/onus-sdk 0.1.0 → 1.0.0

package/README.md

@@ -11,16 +11,19 @@ pnpm add @brunyee-studio/onus-sdk
 ```
 
 ```js
-import { init, captureException } from '@brunyee-studio/onus-sdk';
+import { init, captureException, setReplayCaptureAllowed } from '@brunyee-studio/onus-sdk';
 
 init({
   dsn: 'https://<public-key>@<ingest-host>/<numeric-project-id>',
   release: '1.0.0',
   environment: 'production',
-  // Record every user's session automatically (see "Session replay"):
+  // Configure replay; recording waits for explicit host authorization:
   replays: { sampleRate: 1 },
 });
 
+// Only after the host has determined capture is authorized:
+await setReplayCaptureAllowed(true);
+
 try {
   risky();
 } catch (e) {
@@ -33,7 +36,10 @@ The DSN is public by design (Sentry doctrine); abuse is handled server-side via
 ## Session replay
 
 Two ways to record. **Auto-start (recommended)** — pass a `replays` block to
-`init()`; every session records by default and sampling is an opt-down:
+`init()`; recording is deferred until the host calls `setReplayCaptureAllowed(true)`
+after its own legal/CMP decision. The SDK's in-memory authorization starts
+closed on every page session and is never persisted. After authorization,
+every session records by default and sampling is an opt-down:
 
 ```js
 init({
@@ -41,24 +47,115 @@ init({
   replays: {
     sampleRate: 1, // fraction of sessions recorded (default 1 = all users)
     // sessionId: () => analytics.get_session_id(), // link playback to analytics sessions
-    // recordOptions: { maskAllInputs: true },      // rrweb privacy passthrough
   },
 });
+await setReplayCaptureAllowed(true); // Only after host authorization
+// On withdrawal: stop without flushing unsent events, abort in-flight sends,
+// and remove the replay id from future errors.
+await setReplayCaptureAllowed(false);
+// Re-grant re-runs the configured auto-start (including sampling) and, if
+// selected, starts a fresh recording with a new replay id.
+await setReplayCaptureAllowed(true);
 ```
 
 Errors captured afterwards carry `contexts.replay.replay_id` automatically —
-no extra wiring. `enabled: false` (or omitting the block) opts out entirely.
+no extra wiring. A grant is idempotent while open; after withdrawal, a new grant
+re-runs the latest `init({ replays })` configuration, whereas re-initializing
+without `replays` removes the parked auto-start. `enabled: false` (or omitting
+the block) opts out entirely.
+
+**Behavior change for existing manual callers:** a direct
+`startSessionReplay()` now resolves `null` until the host explicitly calls
+`setReplayCaptureAllowed(true)`. Withdrawal stops recording immediately without
+a tail flush, aborts in-flight requests, and clears the error↔replay link.
+Re-grant permits a fresh manual recording; it never resumes the withdrawn one.
+
+### Privacy defaults (always on)
+
+Capture is privacy-safe by default, and masking happens **before transport**
+(the SDK resolves masks before rrweb serializes anything and before any
+segment leaves the page):
+
+- Non-password, text-like input values are masked via the forced mask map
+  (`maskAllInputs`); password values are **always** masked and cannot be
+  unmasked.
+- Ordinary DOM text nodes are masked by default (`maskTextSelector: '*'`).
+- `input[type="hidden"]`, `input[type="radio"]`, and `input[type="checkbox"]`
+  elements are **blocked entirely** by default: rrweb's masking path skips
+  these types (hidden values and radio/checkbox `value` attributes would
+  otherwise record verbatim), and their checked state is not replayed.
+- Subtrees marked `data-onus-private` are blocked entirely.
+- Canvas recording, cross-origin iframe recording, and inline images stay off.
+- Recorded page URLs omit query strings, fragments, and credentials.
+
+**What is NOT scrubbed:** masking covers input values, ordinary DOM text
+nodes, and the blocked subtree only. DOM **attributes** (for example element
+`title` or the `href` attribute of an anchor), image URLs, **`<style>` /
+stylesheet text** (serialized by rrweb as `_cssText`, outside the
+`maskTextSelector` masking path), and non-replay payloads are recorded
+verbatim. Hosts must block sensitive subtrees with `data-onus-private` (or
+`privacy.blockSelector`) and review sensitive routes and every data path
+before enabling replay in production.
+
+### Opting down per integration
+
+Pass a typed `privacy` object (manual `startSessionReplay` or the `replays`
+block) to deliberately relax non-password masking for that one integration.
+`privacy` flags always win over the bare `recordOptions` passthrough, and a
+hostile `recordOptions` can never defeat masking, enable canvas/iframe
+capture, replace the SDK's `emit`, or pre-pack events through rrweb
+`packFn`/`plugins` (those are stripped: they run before the SDK's emit and
+could bypass Meta href sanitization). Empty, whitespace, or CSS-invalid
+selectors fall back to the safe defaults instead of disabling masking (rrweb
+2.1.1 silently records unmasked on an invalid selector). `privacy.blockSelector`
+is **additive**: it EXTENDS the built-in block list — it can never remove the
+default blocks (`data-onus-private`, hidden, radio, and checkbox inputs).
+There is no
+`privacy: false` convenience switch. URL minimization means sensitive data must still never
+live in the path — hosts should also block sensitive subtrees:
+
+```js
+import { init, setReplayCaptureAllowed } from '@brunyee-studio/onus-sdk';
+import { startSessionReplay } from '@brunyee-studio/onus-sdk/replay';
+
+// Strict default — everything masked (after authorization):
+await setReplayCaptureAllowed(true);
+await startSessionReplay({ dsn });
+
+// Selective text opt-down — only mask text inside a known-sensitive area:
+init({
+  dsn,
+  replays: {
+    privacy: { maskTextSelector: '.sensitive-area' },
+  },
+});
+
+// Extra blocked subtree — privacy.blockSelector ADDS to the built-in block
+// list; [data-onus-private], input[type=hidden], input[type=radio] and
+// input[type=checkbox] stay blocked:
+init({
+  dsn,
+  replays: {
+    privacy: {
+      blockSelector: '.payment-form',
+      ignoreSelector: '.skip-recording',
+    },
+  },
+});
+```
 
 Manual control still works via the separate entrypoint:
 
 ```js
+import { setReplayCaptureAllowed } from '@brunyee-studio/onus-sdk';
 import { startSessionReplay, stopSessionReplay } from '@brunyee-studio/onus-sdk/replay';
 
+await setReplayCaptureAllowed(true); // Manual starts also require authorization.
 const replayId = await startSessionReplay({ dsn, environment: 'production' });
 // Errors captured afterwards carry contexts.replay.replay_id automatically.
 ```
 
-`rrweb` is an **optional peer dependency** — the recorder bundle is lazy-loaded only when recording actually starts, so apps that disable replay never download it. Replay segments are emitted as paired `replay_event` + `replay_recording` envelope items (gzipped) exactly as the ingest routes and the private Storage bucket expect. When capturing all users, review privacy masking (`recordOptions`, e.g. `maskAllInputs`) before enabling in production; replays expire per the team's retention setting (90 days by default).
+`rrweb` is an **optional peer dependency** — the recorder bundle is lazy-loaded only when recording actually starts, so apps that disable replay never download it. Replay segments are emitted as paired `replay_event` + `replay_recording` envelope items (gzipped) exactly as the ingest routes and the private Storage bucket expect. Replays expire per the team's retention setting (90 days by default).
 
 ## Transport semantics
 
@@ -71,6 +168,11 @@ const replayId = await startSessionReplay({ dsn, environment: 'production' });
 ## Tree-shaking & debug flag
 
 - Import only what you use; the replay recorder is isolated in `@brunyee-studio/onus-sdk/replay`.
+- **Known limitation:** do not mix CommonJS `require('@brunyee-studio/onus-sdk')`
+  with ESM imports of the `/replay` subpath in one page. The two builds can
+  create separate module instances with separate in-memory authorization gate
+  state. Use one module system consistently for both SDK entrypoints until
+  dual-instance compatibility has been resolved.
 - Debug logging is gated behind the compile-time flag `__ONUS_DEBUG__`. Strip it in production bundlers:
 
 ```js

package/dist/{chunk-SLWBPQ6C.js → chunk-YPQXIZ4X.js}

@@ -85,18 +85,39 @@ async function gzipText(text) {
 function delay(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
+function untilAborted(operation, signal) {
+  if (!signal) return operation;
+  if (signal.aborted) return Promise.resolve(void 0);
+  return new Promise((resolve, reject) => {
+    const onAbort = () => resolve(void 0);
+    signal.addEventListener("abort", onAbort, { once: true });
+    operation.then(
+      (value) => {
+        signal.removeEventListener("abort", onAbort);
+        resolve(value);
+      },
+      (error) => {
+        signal.removeEventListener("abort", onAbort);
+        reject(error);
+      }
+    );
+  });
+}
 async function sendEnvelope(opts) {
   const fetchImpl = opts.fetchImpl ?? fetch;
   const maxRetries = opts.maxRetries ?? 1;
   const backoffMs = opts.backoffMs ?? 500;
   const sleep = opts.delayImpl ?? delay;
-  const gz = await gzipText(opts.body);
+  if (opts.signal?.aborted) return { ok: false, error: "aborted" };
+  const gz = await untilAborted(gzipText(opts.body), opts.signal);
+  if (opts.signal?.aborted) return { ok: false, error: "aborted" };
   const headers = {
     "Content-Type": "application/x-sentry-envelope",
     "X-Sentry-Auth": opts.authHeader,
     ...gz ? { "Content-Encoding": "gzip" } : {}
   };
   for (let attempt = 0; ; attempt++) {
+    if (opts.signal?.aborted) return { ok: false, error: "aborted" };
     let res;
     try {
       res = await fetchImpl(opts.url, {
@@ -104,11 +125,13 @@ async function sendEnvelope(opts) {
         headers,
         body: gz ?? opts.body,
         // Analytics-style telemetry: never block page unload on the response.
-        keepalive: true
+        keepalive: true,
+        signal: opts.signal
       });
     } catch (e) {
       return { ok: false, error: e instanceof Error ? e.message : "network error" };
     }
+    if (opts.signal?.aborted) return { ok: false, error: "aborted" };
     if (res.ok) return { ok: true, status: res.status };
     if (res.status === 429 && attempt < maxRetries) {
       const retryAfter = Number(res.headers.get("retry-after") ?? "");
@@ -116,7 +139,8 @@ async function sendEnvelope(opts) {
         Number.isFinite(retryAfter) && retryAfter > 0 ? retryAfter * 1e3 : backoffMs * (attempt + 1),
         1e4
       );
-      await sleep(wait);
+      await untilAborted(sleep(wait), opts.signal);
+      if (opts.signal?.aborted) return { ok: false, error: "aborted" };
       continue;
     }
     if (res.status === 429) {
@@ -132,6 +156,68 @@ async function sendEnvelope(opts) {
   }
 }
 
+// src/capture-gate.ts
+var allowed = false;
+var pendingAutoStart = null;
+var autoStartGeneration = 0;
+var grantEpoch = 0;
+var stopReplay = null;
+var clearReplayLink = null;
+var releaseStaleAutoReplay = null;
+function isReplayCaptureAllowed() {
+  return allowed;
+}
+function deferAutoStart(start) {
+  pendingAutoStart = start;
+  const generation = ++autoStartGeneration;
+  releaseStaleAutoReplay?.(generation);
+  return generation;
+}
+function clearAutoStart() {
+  pendingAutoStart = null;
+  releaseStaleAutoReplay?.(++autoStartGeneration);
+}
+function isAutoStartGenerationCurrent(generation) {
+  return generation === autoStartGeneration && pendingAutoStart !== null;
+}
+function getReplayCaptureGrantEpoch() {
+  return grantEpoch;
+}
+function registerReplayLinkClear(clear) {
+  clearReplayLink = clear;
+}
+function registerStaleAutoReplayRelease(release) {
+  releaseStaleAutoReplay = release;
+}
+function registerReplayStop(stop) {
+  stopReplay = stop;
+}
+async function setReplayCaptureAllowed(next) {
+  if (next === allowed) return;
+  allowed = next;
+  grantEpoch++;
+  if (!next) {
+    const stop = stopReplay;
+    stopReplay = null;
+    stop?.();
+    clearReplayLink?.();
+    return;
+  }
+  const start = pendingAutoStart;
+  if (start) await start();
+}
+function resetCaptureGateForTest() {
+  allowed = false;
+  grantEpoch++;
+  clearAutoStart();
+  releaseStaleAutoReplay = null;
+  const stop = stopReplay;
+  stopReplay = null;
+  stop?.();
+  clearReplayLink?.();
+  clearReplayLink = null;
+}
+
 // src/client.ts
 var SDK_NAME = "onus.javascript";
 var SDK_VERSION = "0.1.0";
@@ -183,28 +269,50 @@ function init(options) {
     authHeader: dsn ? buildSentryAuthHeader(dsn, SDK_VERSION) : "",
     replayId: null
   };
+  registerReplayLinkClear(() => setActiveReplayId(null));
   autoReplayStart = null;
-  if (options.replays && options.replays.enabled !== false && dsn) {
-    autoReplayStart = startAutoReplay(options.replays, options);
+  const replays = options.replays;
+  if (replays && replays.enabled !== false && dsn) {
+    let generation;
+    const start = () => {
+      if (!isAutoStartGenerationCurrent(generation) || !isReplayCaptureAllowed()) {
+        return Promise.resolve();
+      }
+      autoReplayStart = startAutoReplay(replays, options, generation, getReplayCaptureGrantEpoch());
+      return autoReplayStart;
+    };
+    generation = deferAutoStart(start);
+    if (isReplayCaptureAllowed()) void start();
+  } else {
+    clearAutoStart();
   }
 }
-async function startAutoReplay(replays, options) {
+async function startAutoReplay(replays, options, generation, grantEpoch2) {
+  const shouldProceed = () => isAutoStartGenerationCurrent(generation) && isReplayCaptureAllowed() && getReplayCaptureGrantEpoch() === grantEpoch2;
   try {
     const rate = typeof replays.sampleRate === "number" && replays.sampleRate >= 0 && replays.sampleRate <= 1 ? replays.sampleRate : 1;
     if (Math.random() >= rate) return;
     const replay = await import("./replay.js");
-    const replayId = await replay.startSessionReplay({
-      dsn: options.dsn,
-      environment: replays.environment ?? options.environment,
-      release: replays.release ?? options.release,
-      sessionId: replays.sessionId,
-      segmentIntervalMs: replays.segmentIntervalMs,
-      maxEventsPerSegment: replays.maxEventsPerSegment,
-      recordOptions: replays.recordOptions,
-      recorderFactory: replays.recorderFactory,
-      fetchImpl: replays.fetchImpl ?? options.fetchImpl
-    });
-    if (replayId) setActiveReplayId(replayId);
+    if (!shouldProceed()) return;
+    const replayId = await replay.startAutoSessionReplay(
+      {
+        shouldProceed,
+        dsn: options.dsn,
+        environment: replays.environment ?? options.environment,
+        release: replays.release ?? options.release,
+        sessionId: replays.sessionId,
+        segmentIntervalMs: replays.segmentIntervalMs,
+        maxEventsPerSegment: replays.maxEventsPerSegment,
+        recordOptions: replays.recordOptions,
+        privacy: replays.privacy,
+        recorderFactory: replays.recorderFactory,
+        fetchImpl: replays.fetchImpl ?? options.fetchImpl
+      },
+      generation
+    );
+    if (replayId && shouldProceed() && replay.activeReplayId() === replayId) {
+      setActiveReplayId(replayId);
+    }
   } catch (e) {
     debugLog("replay auto-start failed", e);
   }
@@ -213,6 +321,7 @@ function isEnabled() {
   return state?.dsn !== null && state?.dsn !== void 0;
 }
 function resetForTest() {
+  resetCaptureGateForTest();
   state = null;
   pending.length = 0;
   autoReplayStart = null;
@@ -292,7 +401,8 @@ function captureCustomEvent(name, props) {
   return id;
 }
 function setActiveReplayId(replayId) {
-  if (state) state.replayId = replayId && /^[a-zA-Z0-9_-]{1,64}$/.test(replayId) ? replayId : null;
+  if (!state || replayId && !isReplayCaptureAllowed()) return;
+  state.replayId = replayId && /^[a-zA-Z0-9_-]{1,64}$/.test(replayId) ? replayId : null;
 }
 function getActiveReplayId() {
   return state?.replayId ?? null;
@@ -311,6 +421,11 @@ export {
   eventId,
   buildEnvelope,
   sendEnvelope,
+  isReplayCaptureAllowed,
+  registerStaleAutoReplayRelease,
+  registerReplayStop,
+  setReplayCaptureAllowed,
+  resetCaptureGateForTest,
   SDK_NAME,
   SDK_VERSION,
   init,