@mushi-mushi/web 0.8.0 → 1.0.0

package/README.md

@@ -26,6 +26,9 @@ Browser SDK for Mushi Mushi — embeddable bug reporting widget with Shadow DOM
 - **Privacy controls** (0.9.1+) — `privacy.maskSelectors`, `privacy.blockSelectors`, `privacy.allowUserRemoveScreenshot` for selector-level screenshot redaction and a one-tap "Remove screenshot" button in the panel
 - **Repro timeline** (0.10+) — auto-captures route changes, clicks, and SDK lifecycle into a normalised `MushiReport.timeline`; pair with `Mushi.setScreen({ name, route, feature })` for screen-level grouping in the admin
 - **Two-way replies** (0.11+) — the panel ships a "Your reports" view that polls comments authored by the dev team and lets the reporter reply, all signed with HMAC against the public API key (no auth user required)
+- **Passive inventory discovery** (0.12+) — opt-in `capture.discoverInventory` ships throttled, PII-free observations (route template, page title, `[data-testid]` values, recent fetch paths, query-param **keys** only, sha256 of user/session id) to `POST /v1/sdk/discovery`. The Mushi server aggregates them into a 30-day `discovery_observed_inventory` view and Claude Sonnet drafts a first-pass `inventory.yaml` proposal you can accept on `/inventory ▸ Discovery`. See `MushiDiscoverInventoryConfig` in [`@mushi-mushi/core`](../core)
+- **SDK observability** (1.0+) — Sentry-style breadcrumb buffer, sticky tags, and a structured `Mushi.captureException(err)` that auto-attaches them. `installAutoBreadcrumbs()` ships route changes, `console.error/warn`, and `[data-testid]` clicks for free. PII is scrubbed from breadcrumb messages and tag string values at report-snapshot time, before anything leaves the browser
+- **Sentry handshake v2** (1.0+) — auto-detects `@sentry/browser` v7 / v8 / v9 and captures the full active scope (`eventId`, `replayId`, `traceId`, `spanId`, `transaction`, `release`, `environment`, `user`, tags, breadcrumbs, issue URL) into `MushiReport.sentryContext`. Tags every Sentry event with `mushi.report_id`, so the admin's report drawer can deep-link `Open in Sentry` and Sentry's issue page can deep-link back into Mushi
 - **SDK identity & freshness** (0.8+) — every report ships `sdkPackage` + `sdkVersion`; the widget polls `/v1/sdk/latest-version` and surfaces an outdated banner (configurable via `widget.outdatedBanner`)
 - **Self-noise filters** (0.7.1+) — internal Mushi requests are tagged with `X-Mushi-Internal` and excluded from network capture + `apiCascade`; configurable `capture.ignoreUrls` and `proactive.apiCascade.ignoreUrls` for host-app endpoints you also don't want counted
 - **`Mushi.diagnose()`** (0.7.1+) — one-call CSP / runtime-config / capture / widget health check (also runs without an init for pre-install smoke tests)
@@ -262,6 +265,54 @@ ring buffer. Submissions ship the trail as `MushiReport.timeline` and the admin
 console renders it as a chronological "what happened before the report" card on
 `/reports/:id`.
 
+### Power-user APIs (1.0+)
+
+Once `Mushi.init()` has resolved (cloud or self-hosted) the returned instance
+exposes a Sentry-style observability surface that ships on every subsequent
+report — without you having to plumb it through the report payload yourself:
+
+```typescript
+const mushi = Mushi.init({ projectId: 'proj_xxx', apiKey: 'mushi_xxx' });
+
+// Identify the active reporter (also sent to Sentry if @sentry/browser is loaded).
+mushi.identify({ id: 'usr_42', email: 'aya@example.com', segment: 'beta' });
+
+// Sticky scalar tags. Up to 64 keys; values are string | number | boolean.
+mushi.setTag('feature', 'checkout-v2');
+mushi.setTags({ plan: 'pro', region: 'apac', experiment: 'B' });
+mushi.clearTag('experiment');
+
+// Manual breadcrumbs — route changes / console.error / [data-testid] clicks
+// are captured automatically by `installAutoBreadcrumbs`.
+mushi.addBreadcrumb({
+  category: 'business',
+  level: 'info',
+  message: 'cart.checkout_started',
+  data: { itemCount: 3, currency: 'JPY' },
+});
+
+// Structured exception capture. Accepts Error, string, plain object, null,
+// or undefined — anything `try { } catch (e) { }` can land on. The SDK
+// normalises the throw, attaches the breadcrumb buffer + sticky tags +
+// Sentry context, and submits as a `bug` report.
+try {
+  await runCheckout();
+} catch (err) {
+  mushi.captureException(err, {
+    level: 'error',
+    tags: { surface: 'checkout' },
+    extras: { orderId: 'ord_123' },
+  });
+}
+```
+
+The dedicated server columns `reports.breadcrumbs` (jsonb, GIN-indexed),
+`reports.tags` (jsonb, GIN-indexed), and `reports.sentry_trace_id` /
+`sentry_release` / `sentry_environment` (text, btree-indexed) make the
+admin's `/reports` page filterable by `tags @> '{feature: checkout-v2}'`,
+`?trace=…`, `?release=…`, `?sentryEnv=…` in O(index-lookup) instead of an
+O(full-scan) traversal of `custom_metadata`.
+
 ### Two-way replies (Your reports)
 
 The widget mounts a "Your reports" tab that lists this reporter's history,
@@ -283,6 +334,47 @@ The DB-side `report_comments_fanout_to_reporter` trigger creates a
 `reporter_notifications` row whenever a `visible_to_reporter` admin comment
 lands, so the unread count stays in sync without polling.
 
+### Passive inventory discovery (v2.1)
+
+```typescript
+Mushi.init({
+  projectId: 'proj_xxx',
+  apiKey: 'mushi_xxx',
+  capture: {
+    // `true` enables defaults (60s per-route throttle, heuristic
+    // route normalisation). Pass an object for fine-grained control.
+    discoverInventory: {
+      enabled: true,
+      throttleMs: 60_000,
+      // Optional — your framework's known route templates so we don't
+      // have to guess `/practice/abc-123` → `/practice/[id]`.
+      routeTemplates: ['/practice/[id]', '/lessons/[slug]'],
+    },
+  },
+});
+```
+
+Each emission is one row on `POST /v1/sdk/discovery`:
+
+```jsonc
+{
+  "route": "/practice/[id]",
+  "page_title": "Practice — Glot.it",
+  "dom_summary": "…≤200 chars…",
+  "testids": ["practice-submit", "practice-hint"],
+  "network_paths": ["/api/practice/run", "/rest/v1/answers"],
+  "query_param_keys": ["lang"],
+  "user_id_hash": "sha256(…)",
+  "observed_at": "2026-05-04T12:00:00Z"
+}
+```
+
+Open `/inventory ▸ Discovery` in the admin to watch routes accumulate,
+hit **Generate proposal**, then **Accept** to write the LLM-drafted
+`inventory.yaml` into the project. Nothing else changes about the SDK —
+the discovery channel is independent of the bug-report widget and stays
+quiet under `prefers-reduced-motion` / when the tab is hidden.
+
 ## Test utilities (`./test-utils`)
 
 Deterministic Playwright / jsdom helpers, published as a separate

package/SECURITY.md

@@ -19,15 +19,59 @@ If you discover a security vulnerability, please report it responsibly.
 
 **Do NOT open a public GitHub issue.**
 
-Instead, email: **kensaurus@gmail.com**
+Use either channel below:
+
+1. **GitHub Private Vulnerability Reporting** — strongly preferred.
+   <https://github.com/kensaurus/mushi-mushi/security/advisories/new>
+   Routes the report into a private advisory with built-in CVE issuance,
+   patch coordination, and contributor-credit workflow.
+2. **Email** — `kensaurus@gmail.com`, subject prefix `[mushi-security]`.
+   PGP welcome but not required.
 
 Include:
 - Description of the vulnerability
-- Steps to reproduce
-- Impact assessment
+- Steps to reproduce (smallest reproducer wins)
+- Impact assessment (what an attacker gains)
 - Suggested fix (if any)
+- Whether you want public credit (and how to spell your name)
+
+### Coordinated-disclosure timeline
+
+| Day | Action |
+|-----|--------|
+| 0 | Report received |
+| ≤ 2 | Acknowledgment + assigned a tracking ID |
+| ≤ 7 | Triage complete: severity assigned (CVSS 3.1) and target patch date communicated |
+| ≤ 30 | Patch released for critical / high (CVSS ≥ 7.0); ≤ 60 days for medium; best-effort for low |
+| Patch + 7 | Public advisory + CVE published; reporter credited unless they declined |
+| Patch + 90 | Embargo expires regardless; if upstream is unresponsive, the reporter is free to publish |
+
+### Safe harbor
+
+Good-faith security research on Mushi Mushi is welcome. If you stay
+within the rules below, we will not pursue legal action, will not ask
+your hosting provider to take you offline, and will publicly credit your
+work:
+
+- Test only against your own self-hosted instance, the public demo at
+  <https://kensaur.us/mushi-mushi/admin/>, or accounts you own.
+- Do not access, exfiltrate, or modify data belonging to other users.
+- Do not run automated scanning that affects availability for others
+  (rate-limit your tooling, exclude `/health`).
+- Disclose privately first (channels above); do not publish before the
+  embargo above expires.
+- Do not intentionally exploit a finding to escalate beyond proving it
+  exists.
+
+If a finding requires touching production data to confirm, **stop and
+ask first** — describe what you'd need to do and we'll spin up a sandbox.
+
+### Hall of fame
 
-We will acknowledge receipt within 48 hours and aim to release a patch within 7 days for critical issues.
+Researchers who report a confirmed vulnerability are credited in the
+release notes for the patched version and added to
+[`docs/SECURITY_HALL_OF_FAME.md`](./docs/SECURITY_HALL_OF_FAME.md) (with
+permission).
 
 ## Scope
 
@@ -48,6 +92,125 @@ We will acknowledge receipt within 48 hours and aim to release a patch within 7
 - **Rotate API keys** regularly via the admin console
 - **Enable SSO** for team projects (Enterprise tier)
 - **Review audit logs** periodically for suspicious activity
+- **Verify SDK integrity** with `npm audit signatures` after install
+- **Set `Content-Security-Policy`** on any page embedding the Mushi widget;
+  the widget itself ships with `script-src 'self'` and does not load
+  remote scripts.
+
+## Threat model
+
+What we treat as in-scope attacker capabilities, and what we don't.
+
+| Capability | In scope | Notes |
+|-----------|----------|-------|
+| Unauthenticated network attacker hitting public endpoints | ✅ | Rate-limit + HMAC + replay protection on every webhook endpoint (`packages/server/supabase/functions/_shared/webhook-middleware.ts`). |
+| Authenticated user trying to read another tenant's data | ✅ | Postgres RLS on every `public.*` table; advisor lints reviewed monthly. |
+| Authenticated user trying to escalate to super-admin | ✅ | Role lives in `auth.users.raw_app_meta_data.role`; cannot be self-edited via PostgREST. |
+| Compromised dependency (npm supply-chain attack) | ✅ | 7-day cooldown + provenance + Harden-Runner + pinned SHAs (see "Supply-chain hardening" below). |
+| Stolen API key | ✅ | Per-key scopes (`api_key_has_scope`), revocation via admin console, audit log of every use. |
+| User pasting a Stripe / OpenAI / GitHub PAT into a bug report | ✅ | PII scrubber redacts ~15 vendor token formats client-side before the report leaves the device. Mirrors `packages/core/src/pii-scrubber.ts` across iOS, Android, Flutter, React Native. |
+| Stolen end-user device with the SDK installed | ⚠️ partial | Offline queue is AsyncStorage / Keychain / SharedPreferences — no app-level encryption beyond the OS default. Reports waiting to flush are vulnerable to a forensic attacker. |
+| Compromised Supabase service-role key | ❌ | Treated as a tier-0 incident; would require key rotation and audit-log forensics. Not defendable in software. |
+| Compromise of `kensaurus@gmail.com` | ❌ | Treated as a project-fork event; downstream consumers should pin to the last known-good version and follow the new release channel. |
+| Physical / OS-level attacker on an end-user device | ❌ | Out of scope. |
+| Malicious fork using the Mushi name to ship malware | ❌ (technical) ✅ (legal) | The MIT/BSL grant lets the fork exist; the trademark policy (`TRADEMARK.md`) makes shipping it under the Mushi name an infringement we will pursue. |
+
+## Data handling and PII
+
+### What the SDK collects by default
+
+| Field | Scope | PII risk |
+|-------|-------|----------|
+| URL / route the user was on | Always | Low — strip query strings if your routes encode user IDs. |
+| Browser / OS / device | Always | None |
+| Console errors (last 50) | Opt-in via `captureConsole: true` | Medium — can include user data your code logs. |
+| Network failures (URL + status) | Opt-in via `captureNetwork: true` | Medium — query params logged as-is unless you redact in-app. |
+| User id / email / role | Only if you call `setUser()` | High — only set what you need; we do not auto-discover. |
+| Session replay frames | Off by default | High — handled by the masking layer; passwords / cards / opted-out elements never leave the page. |
+| Free-text bug description | Always | Medium — passed through the PII scrubber (see below). |
+
+### What the PII scrubber redacts before send
+
+Implemented identically across `@mushi-mushi/core`, the iOS, Android,
+Flutter, and React Native SDKs. Defaults are below — every category can
+be toggled off, but `secretTokens` is on by default and we recommend
+keeping it that way.
+
+| Category | Default | Patterns |
+|----------|---------|----------|
+| `ssns` | on | `123-45-6789` |
+| `creditCards` | on | 12–19 digit Luhn-shaped sequences with optional separators |
+| `secretTokens` | on | AWS access key (`AKIA…` / `ASIA…`), AWS secret (`aws_secret_access_key=…`), Stripe (`sk_live_…`, `sk_test_…`, `rk_…`, `pk_…`), Slack (`xox[abpor]-…`), GitHub PAT (`ghp_…`, `github_pat_…`), OpenAI (`sk-…`, `sk-proj-…`), Anthropic (`sk-ant-…`), Google API (`AIza…`), JWT (`eyJ…` 3-segment) |
+| `emails` | on | RFC-5322 lite |
+| `phones` | on | E.164 with optional country code |
+| `ipAddresses` | off | IPv4 (off because internal IPs are usually not PII and noise hurts triage) |
+| `ipv6` | off | Same |
+
+The fields scrubbed are:
+
+- `description` — primary free-text field of every bug report
+- `summary` — short summary, in the same composer
+- `breadcrumbs[].message` — auto-captured user-action trail (clicks, route changes, console messages)
+
+Structured fields you set explicitly (`metadata.userEmail`,
+`metadata.userId`, etc.) are intentionally **not** scrubbed — those are
+opt-in attribution data, and silently rewriting them would break
+support workflows.
+
+### Where data lives
+
+- **Reports & telemetry** — Supabase Postgres in the `us-west-1` region.
+- **Session replays** — Supabase Storage, same region. Lifecycle policy
+  trims replays older than 30 days unless explicitly retained from the
+  admin console.
+- **Inbound webhook bodies** — only a SHA-256 hash + `delivery_id` of
+  the body is persisted (`webhook_audit_log`). The full body is
+  processed in memory and discarded.
+- **Outbound integrations** (Slack, Jira, …) — Mushi is a sender only;
+  the receiving system's retention applies.
+
+### Encryption
+
+| Surface | At rest | In transit |
+|---------|---------|------------|
+| Postgres (Supabase) | AES-256 (Supabase default) | TLS 1.2+ |
+| Supabase Storage (replays) | AES-256 | TLS 1.2+ |
+| Edge Function ↔ Postgres | — | TLS via the Supavisor pooler |
+| SDK ↔ ingest endpoint | — | TLS 1.2+ enforced; HSTS preload on `kensaur.us` |
+| Inbound webhooks | — | TLS terminated at CloudFront / Supabase edge |
+| Audit log integrity | append-only by RLS; no in-row signing | — |
+
+### Cryptographic primitives
+
+| Use | Algorithm | Implementation |
+|-----|-----------|---------------|
+| Webhook HMAC verification (Sentry, GitHub, Datadog, Honeycomb, Grafana, Bugsnag, Rollbar, Crashlytics) | HMAC-SHA256, constant-time compare | Web Crypto in Deno; `crypto.subtle.timingSafeEqual` analogue |
+| AWS SNS subscription confirmation | RSA-SHA1 / RSA-SHA256 | Deno `crypto.subtle.verify` with the cert from `SigningCertURL` (URL allow-listed to `*.sns.*.amazonaws.com`) |
+| Opsgenie JWT shared-token | HS256 with `aud` claim verification | `jose` (Deno-compatible) |
+| API-key hashing (database) | SHA-256 prefix + bcrypt secret half | `pgcrypto` |
+| Provenance attestations (npm) | Sigstore (Fulcio + Rekor) | `npm publish --provenance` |
+
+We deliberately do not roll our own crypto. If you find an algorithm or
+library above that has been deprecated, please file a security advisory.
+
+### Operator security checklist
+
+When you provision a new self-hosted Mushi instance:
+
+- [ ] Set `auth_leaked_password_protection = true` in Supabase Auth
+      (HaveIBeenPwned blocklist; flagged as `auth_leaked_password_protection`
+      in the security advisor).
+- [ ] Enable at least two MFA factors in Supabase Auth (`auth_insufficient_mfa_options`).
+- [ ] Rotate the service-role key on day 1, then quarterly.
+- [ ] Restrict Postgres direct connections to your CI / migration runners
+      via Supabase network restrictions.
+- [ ] Run `pnpm dlx supabase advisors --project-ref <ref>` after every
+      migration; aim for zero ERROR-level findings.
+- [ ] Configure a Supabase log drain to your SIEM if you are subject to
+      SOC 2 / ISO 27001.
+- [ ] Set CSP `frame-ancestors` on the host page if you embed the Mushi
+      widget (the widget is iframe-friendly but does not enforce
+      framing constraints itself).
 
 ## Supply-chain hardening (how this package is protected)