@arvoretech/bug-jar 0.3.2 → 0.6.0

package/README.md

@@ -1,12 +1,12 @@
 # 🪲 Bug Jar
 
-Capture everything for non-technical people to help debug. One script tag, zero config.
+Capture everything for non-technical people to help debug. One debug link, zero config.
 
-Bug Jar is a lightweight JavaScript library that silently records all browser activity (network requests, console logs, errors, user actions, performance metrics, and more) and lets anyone — even non-technical users — generate a complete debug report with a single click.
+Bug Jar is a lightweight JavaScript library that silently records all browser activity (network requests, console logs, errors, user actions, performance metrics, and more) and lets you capture a complete, encrypted debug session from a one-time debug link.
 
 ## Why?
 
-Because asking someone to "open DevTools and check the Network tab" doesn't scale. Bug Jar gives your support team, QA, and stakeholders a one-click way to capture everything developers need to reproduce and fix bugs.
+Because asking someone to "open DevTools and check the Network tab" doesn't scale. Bug Jar gives your support team and QA a link they can send to anyone to capture everything developers need to reproduce and fix bugs.
 
 ## What it captures
 
@@ -26,30 +26,19 @@ Because asking someone to "open DevTools and check the Network tab" doesn't scal
 
 ## Quick Start
 
-### Script tag (zero config)
+Bug Jar runs as a **debug session**: staff generates a one-time link, the user
+opens it in the real app, and the encrypted package is uploaded to S3. See
+[Debug Session Mode](#debug-session-mode-encrypted-upload-to-s3) below.
 
 ```html
 <script src="https://unpkg.com/@arvoretech/bug-jar"></script>
 <script>
-  BugJar.init();
+  BugJar.init({
+    debugSessionEndpoint: 'https://api.arvore.com.br/debug-sessions',
+  })
 </script>
 ```
 
-### NPM
-
-```bash
-npm install @arvoretech/bug-jar
-```
-
-```typescript
-import { init } from '@arvoretech/bug-jar'
-
-init({
-  endpoint: 'https://your-api.com/bug-reports',
-  uiPosition: 'bottom-right',
-})
-```
-
 ## Configuration
 
 ```typescript
@@ -74,16 +63,12 @@ init({
   // Privacy — fields containing these strings are redacted
   sensitiveFields: ['password', 'token', 'secret', 'authorization', 'cookie', 'session', 'credit_card', 'cvv', 'ssn', 'cpf'],
 
-  // Where to send reports (if not set, downloads as JSON file)
-  endpoint: 'https://your-api.com/bug-reports',
-
   // Callback when report is generated
   onCapture: (report) => console.log(report),
 
-  // UI widget
-  ui: true,
-  uiPosition: 'bottom-right', // bottom-right | bottom-left | top-right | top-left
-  uiLabel: 'Reportar Bug',
+  // Debug session
+  debugSessionEndpoint: 'https://api.arvore.com.br/debug-sessions',
+  // debugToken is read automatically from the ?debug=<token> query param
 })
 ```
 
@@ -92,7 +77,7 @@ init({
 ```typescript
 import { BugJar } from '@arvoretech/bug-jar'
 
-const jar = new BugJar({ ui: false })
+const jar = new BugJar()
 jar.start()
 
 // Later, capture a report programmatically
@@ -105,12 +90,72 @@ await fetch('/api/bugs', {
 })
 ```
 
+## Debug Session Mode (encrypted upload to S3)
+
+For non-technical users, staff can generate a one-time debug link. The user opens
+the link in the real app, reproduces the bug, and Bug Jar records the whole flow,
+encrypts the package end-to-end in the browser, and uploads it straight to a
+private S3 bucket via a presigned URL. No AWS credentials ever reach the browser.
+
+```html
+<script src="https://unpkg.com/@arvoretech/bug-jar"></script>
+<script>
+  BugJar.init({
+    debugSessionEndpoint: 'https://api.arvore.com.br/debug-sessions',
+    // debugToken is read automatically from the ?debug=<token> query param
+  })
+</script>
+```
+
+Flow:
+
+1. Staff (admin) calls `POST /debug-sessions` with the target app URL and gets back
+   a `debugLink` (`https://app.../?debug=<token>`), the server public key, and an expiry.
+2. The user opens the link. Bug Jar detects `?debug=<token>`, persists the token in
+   a `.arvore.com.br` cookie, fetches the session, starts screen recording, and
+   shows an animated **session border** (no button, no banner).
+3. The user just uses the app. The session survives navigation across apps
+   (app-v2 → legacy → reader) by re-hydrating the token from the cookie on each
+   page. Each page streams **encrypted chunks** to S3 in real time:
+   - **data** (network/console/errors/actions/storage) every 5s as JSONL
+   - **video** chunks straight from `MediaRecorder` as they are produced
+   Chunks are uploaded to `debug/<token>/<pageId>/<stream>/<seq>.bin` via per-chunk
+   presigned PUT URLs (`POST /debug-sessions/:token/chunk-url`). Page metadata goes
+   to `debug/<token>/<pageId>/meta.json` (`POST /debug-sessions/:token/meta`).
+4. Staff reconstructs the session offline:
+   ```bash
+   BUG_JAR_API=https://api.arvore.com.br/debug-sessions \
+   BUG_JAR_API_TOKEN=<admin-jwt> \
+   node scripts/decrypt-session.cjs <token> ./out
+   ```
+   This reads the X25519 private key from Secrets Manager (`bug-jar/keypair`),
+   downloads all chunks via `GET /debug-sessions/:token/download`, decrypts each
+   per-page stream, and writes `<pageId>/data.jsonl`, `<pageId>/video.webm`,
+   `<pageId>/meta.json`.
+
+## Encryption
+
+Each stream (data and video, per page) is encrypted with libsodium
+`crypto_secretstream_xchacha20poly1305`: a random symmetric key drives the stream,
+and that key is sealed with `crypto_box_seal` (X25519) to the server public key.
+The first chunk of every stream is `[magic][version][sealedKeyLen][sealedKey][header]`;
+subsequent chunks are the encrypted stream messages, the last carrying `TAG_FINAL`.
+Chunks leave the browser already unreadable; only the holder of the X25519 private
+key can open them. `libsodium-wrappers` is loaded dynamically, so it only ships
+when debug mode is actually used.
+
+> Cross-app continuity works because all apps live under `*.arvore.com.br` and
+> share the session cookie. Screen recording restarts per app (the browser does
+> not allow `getDisplayMedia` to persist across full page loads / origins), so the
+> video is reconstructed per page rather than as one continuous file.
+
+
 ## Privacy & Security
 
 - Sensitive fields are automatically redacted (passwords, tokens, secrets, etc.)
 - Password inputs are never captured
 - You control what gets captured via configuration
-- No data leaves the browser unless you configure an endpoint
+- No data leaves the browser unless a debug session is active
 - All processing happens client-side
 
 ## Browser Support

package/dist/index.d.mts

@@ -15,11 +15,8 @@ interface BugJarConfig {
     sensitiveFields: string[];
     endpoint?: string;
     onCapture?: (report: BugReport) => void;
-    ui: boolean;
-    uiPosition: "bottom-right" | "bottom-left" | "top-right" | "top-left";
-    uiLabel: string;
-    hideOnMobile?: boolean;
-    uiCompactOnMobile?: boolean;
+    debugToken?: string;
+    debugSessionEndpoint?: string;
 }
 interface NetworkEntry {
     id: string;
@@ -136,6 +133,12 @@ declare function generateSummary(report: BugReport): string;
 
 declare function exportAsZip(report: BugReport, videoBlob: Blob | null): Promise<Blob>;
 
+interface DebugSessionPayload {
+    token: string;
+    publicKey: string;
+    expiresAt: number;
+}
+
 declare class BugJar {
     private config;
     private network;
@@ -148,7 +151,13 @@ declare class BugJar {
     private screenshot;
     private featureFlags;
     private screenRecorder;
-    private ui;
+    private sessionBorder;
+    private debugSession;
+    private dataUploader;
+    private videoUploader;
+    private pageId;
+    private dataInterval;
+    private finalized;
     private started;
     constructor(config?: Partial<BugJarConfig>);
     start(): void;
@@ -158,7 +167,12 @@ declare class BugJar {
     capture(userDescription?: string): Promise<BugReport>;
     captureAndExport(userDescription?: string): Promise<BugReport>;
     getReport(): Promise<BugReport>;
+    private startDebugSession;
+    private startDataStreaming;
+    private registerFlushHandlers;
+    private finalizePage;
+    endDebugSession(): void;
 }
 declare function init(config?: Partial<BugJarConfig>): BugJar;
 
-export { BugJar, type BugJarConfig, type BugReport, BugJar as default, exportAsZip, generateSummary, init };
+export { BugJar, type BugJarConfig, type BugReport, type DebugSessionPayload, BugJar as default, exportAsZip, generateSummary, init };

package/dist/index.d.ts

@@ -15,11 +15,8 @@ interface BugJarConfig {
     sensitiveFields: string[];
     endpoint?: string;
     onCapture?: (report: BugReport) => void;
-    ui: boolean;
-    uiPosition: "bottom-right" | "bottom-left" | "top-right" | "top-left";
-    uiLabel: string;
-    hideOnMobile?: boolean;
-    uiCompactOnMobile?: boolean;
+    debugToken?: string;
+    debugSessionEndpoint?: string;
 }
 interface NetworkEntry {
     id: string;
@@ -136,6 +133,12 @@ declare function generateSummary(report: BugReport): string;
 
 declare function exportAsZip(report: BugReport, videoBlob: Blob | null): Promise<Blob>;
 
+interface DebugSessionPayload {
+    token: string;
+    publicKey: string;
+    expiresAt: number;
+}
+
 declare class BugJar {
     private config;
     private network;
@@ -148,7 +151,13 @@ declare class BugJar {
     private screenshot;
     private featureFlags;
     private screenRecorder;
-    private ui;
+    private sessionBorder;
+    private debugSession;
+    private dataUploader;
+    private videoUploader;
+    private pageId;
+    private dataInterval;
+    private finalized;
     private started;
     constructor(config?: Partial<BugJarConfig>);
     start(): void;
@@ -158,7 +167,12 @@ declare class BugJar {
     capture(userDescription?: string): Promise<BugReport>;
     captureAndExport(userDescription?: string): Promise<BugReport>;
     getReport(): Promise<BugReport>;
+    private startDebugSession;
+    private startDataStreaming;
+    private registerFlushHandlers;
+    private finalizePage;
+    endDebugSession(): void;
 }
 declare function init(config?: Partial<BugJarConfig>): BugJar;
 
-export { BugJar, type BugJarConfig, type BugReport, BugJar as default, exportAsZip, generateSummary, init };
+export { BugJar, type BugJarConfig, type BugReport, type DebugSessionPayload, BugJar as default, exportAsZip, generateSummary, init };