@mushi-mushi/web 0.5.1 → 0.8.0

package/CONTRIBUTING.md

@@ -33,6 +33,10 @@ pnpm lint         # ESLint
 pnpm format       # Prettier
 ```
 
+Ad-hoc screenshots captured during UI reviews can live temporarily at the repo
+root, but root-level `*.png` files are intentionally ignored. Canonical
+screenshots that should be versioned belong under `docs/screenshots/`.
+
 ### Working on a single package
 
 ```bash

package/README.md

@@ -17,8 +17,18 @@ Browser SDK for Mushi Mushi — embeddable bug reporting widget with Shadow DOM
 - On-device pre-filter (blocks spam before server submission)
 - Client-side rate limiting (token bucket self-throttle)
 - Light/dark theme with auto-detection (`prefers-color-scheme`)
+- **Trigger modes** (0.6+) — `auto` / `edge-tab` / `attach` (bring-your-own-button) / `manual` / `hidden`, plus `smartHide`, `hideOnSelector`, `hideOnRoutes`, configurable `inset` and `respectSafeArea`
+- **Runtime trigger APIs** — `Mushi.show()`, `Mushi.hide()`, `Mushi.attachTo(selector)`, `Mushi.setTrigger(mode)`, `Mushi.openWith(category)`
+- **Widget anchor** (0.9+) — `widget.anchor` accepts raw CSS (including `var()` and `env()`) so the launcher honours your app shell's tab bars, docks, mini-players, and cookie banners without Shadow-DOM patching
+- **Presets** (0.9+) — `preset: 'production-calm' | 'beta-loud' | 'internal-debug' | 'manual-only'` flips a coherent bundle of widget / capture / proactive defaults so prod apps stay quiet and internal builds stay loud
 - **Proactive triggers** — rage click, long task, API cascade failure detection
 - **Report fatigue prevention** — session limits, cooldowns, permanent suppression
+- **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)
+- **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)
 - Keyboard-first: `Esc` to close, `⌘/Ctrl + Enter` to submit, focus-trapped panel
 - Honours `prefers-reduced-motion` (animations collapse to instant)
 
@@ -84,6 +94,45 @@ Mushi.init({
 });
 ```
 
+### Bring your own launcher (`trigger: 'attach'`)
+
+For mature production apps, prefer hosting the launcher inside your own help
+menu, settings page, or beta banner. Mushi will not inject any UI of its own.
+
+```typescript
+const mushi = Mushi.init({
+  projectId: 'proj_xxx',
+  apiKey: 'mushi_xxx',
+  widget: {
+    trigger: 'attach',
+    attachToSelector: '[data-mushi-feedback]',
+  },
+});
+
+mushi.attachTo('#support-menu-feedback');
+mushi.hide();
+```
+
+### Smart-hide (`trigger: 'auto'` with viewport awareness)
+
+```typescript
+Mushi.init({
+  projectId: 'proj_xxx',
+  apiKey: 'mushi_xxx',
+  widget: {
+    trigger: 'auto',
+    smartHide: { onMobile: 'edge-tab', onScroll: 'shrink', onIdleMs: 900 },
+    inset: { bottom: 96, right: 20 },
+    hideOnSelector: '[data-fullscreen-player]',
+    hideOnRoutes: ['/checkout/payment'],
+    respectSafeArea: true,
+  },
+});
+```
+
+See [Trigger modes](https://docs.mushimushi.dev/concepts/trigger-modes) for the
+full posture matrix (`auto` / `edge-tab` / `attach` / `manual` / `hidden`).
+
 ### With Proactive Triggers
 
 Proactive triggers are wired into `Mushi.init()` automatically when `config.proactive` is provided. The SDK opens the widget when a trigger fires, gated by fatigue prevention:
@@ -122,6 +171,118 @@ setupProactiveTriggers({
 });
 ```
 
+### Self-noise filters and CSP diagnostics
+
+Out of the box the SDK tags every request it makes with `X-Mushi-Internal` and skips
+those URLs in `capture.network` + `proactive.apiCascade`, so an unconfigured CSP
+or a flaky local Supabase stack can no longer make Mushi report on Mushi:
+
+```typescript
+Mushi.init({
+  projectId: 'proj_xxx',
+  apiKey: 'mushi_xxx',
+  // 'auto' (default) skips the runtime-config fetch on localhost endpoints —
+  // pass `true` to force it everywhere, `false` to disable entirely.
+  runtimeConfig: 'auto',
+  capture: {
+    network: true,
+    ignoreUrls: [/\/api\/internal\//, 'https://posthog.example.com'],
+  },
+  proactive: {
+    apiCascade: {
+      enabled: true,
+      ignoreUrls: ['https://feature-flags.example.com'],
+    },
+  },
+});
+
+const health = await Mushi.diagnose();
+// → { apiEndpointReachable, cspAllowsEndpoint, widgetMounted, shadowDomAvailable,
+//     dialogSupported, runtimeConfigLoaded, captureScreenshotAvailable,
+//     captureNetworkIntercepting, sdkVersion }
+```
+
+`Mushi.diagnose()` works **before** `Mushi.init()` too — call it from a debug
+console or installer wizard to surface CSP / endpoint problems with zero risk
+of accidentally booting the widget.
+
+### Presets and widget anchor
+
+```typescript
+Mushi.init({
+  projectId: 'proj_xxx',
+  apiKey: 'mushi_xxx',
+  // production-calm = manual trigger, screenshot only on report, no proactive prompts
+  // beta-loud       = proactive triggers + console + network always on
+  // internal-debug  = above + verbose debug + always-on screenshot
+  // manual-only     = trigger only, every proactive surface off
+  preset: 'production-calm',
+  widget: {
+    // Raw CSS strings (including `var()` and `env()`) win over `position` /
+    // `inset` so the launcher tracks your app shell's tab bars or mini-player.
+    anchor: {
+      bottom: 'calc(var(--app-dock-h, 0px) + env(safe-area-inset-bottom))',
+      right: 'calc(0.75rem + env(safe-area-inset-right))',
+    },
+    brandFooter: true,
+    outdatedBanner: 'auto',
+  },
+});
+```
+
+### Privacy and screenshot redaction
+
+```typescript
+Mushi.init({
+  projectId: 'proj_xxx',
+  apiKey: 'mushi_xxx',
+  privacy: {
+    maskSelectors: ['[data-private]', 'input', '.thai-answer-draft'],
+    blockSelectors: ['[data-payment]', '[data-auth-token]'],
+    allowUserRemoveScreenshot: true,
+  },
+});
+```
+
+`maskSelectors` paints a solid block over matching elements before serialisation;
+`blockSelectors` removes them entirely. `allowUserRemoveScreenshot` adds a
+"Remove screenshot" affordance next to the attachment chip in the panel, so the
+reporter can yank a screenshot they didn't realise contained sensitive data.
+
+### Repro timeline and `setScreen()`
+
+```typescript
+const mushi = Mushi.init({ /* ... */ });
+mushi.setScreen({ name: 'Chat', route: '/chat', feature: 'roleplay' });
+```
+
+The SDK auto-records `route` (initial + `pushState` / `popstate` / `hashchange`),
+`click` (with selector + text snippet), and `screen` events into a 120-entry
+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`.
+
+### Two-way replies (Your reports)
+
+The widget mounts a "Your reports" tab that lists this reporter's history,
+unread admin replies (with a count badge on the trigger), and a reply input.
+Calls are signed with an HMAC over `projectId.timestamp.sha256(reporterToken)`
+using the public API key as the secret, so no Supabase auth is required.
+
+```typescript
+Mushi.init({
+  projectId: 'proj_xxx',
+  apiKey: 'mushi_xxx',
+  widget: { brandFooter: true, outdatedBanner: 'auto' },
+});
+```
+
+Endpoints (Edge Function): `GET /v1/reporter/reports`,
+`GET /v1/reporter/reports/:id/comments`, `POST /v1/reporter/reports/:id/reply`.
+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.
+
 ## Test utilities (`./test-utils`)
 
 Deterministic Playwright / jsdom helpers, published as a separate
@@ -131,11 +292,14 @@ entry-point so production bundles pay nothing for them:
 import { triggerBug, openReport, waitForQueueDrain } from '@mushi-mushi/web/test-utils';
 ```
 
-| Export              | Purpose                                                                 |
-|---------------------|-------------------------------------------------------------------------|
-| `triggerBug(opts?)` | Submit a report bypassing the widget. Returns the server-assigned id.   |
-| `openReport(cat?)`  | Open the widget programmatically without submitting.                    |
-| `waitForQueueDrain` | Resolve once the offline queue is empty (number remaining at timeout).  |
+| Export                       | Purpose                                                                                                                     |
+|------------------------------|-----------------------------------------------------------------------------------------------------------------------------|
+| `triggerBug(opts?)`          | Submit a report bypassing the widget. Returns the server-assigned id.                                                       |
+| `openReport(cat?)`           | Open the widget programmatically without submitting.                                                                        |
+| `openMushiWidget(cat?)`      | Alias for `openReport` — Playwright-friendly name for the dogfood contract suite.                                           |
+| `waitForQueueDrain`          | Resolve once the offline queue is empty (number remaining at timeout).                                                      |
+| `expectMushiReady(opts?)`    | Resolve with a `MushiDiagnosticsResult` once the SDK is initialised and reachable. Fails if `apiEndpointReachable === false`. |
+| `expectNoMushiSelfCascade()` | Run an action and assert no internal Mushi request fired the `api_cascade` proactive trigger. Catches CSP / runtime-config self-noise. |
 
 Every helper no-ops when `Mushi.getInstance()` returns `null`, so
 conditional-wiring tests (e.g. cloud vs local targets) don't need to

package/SECURITY.md

@@ -48,3 +48,77 @@ 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
+
+## Supply-chain hardening (how this package is protected)
+
+Mushi Mushi is built and published with the controls below. Consumers can
+verify each control independently — the goal is to make tampering both
+difficult and detectable.
+
+### Publish-time controls
+
+| Control | What it does | How to verify |
+|---|---|---|
+| **npm Trusted Publisher (OIDC)** | Every release is published from `.github/workflows/release.yml` on `master` using a short-lived OIDC token. Long-lived `NPM_TOKEN` is not used for publishing. | `npm view @mushi-mushi/<pkg> --json` shows `"trustedPublisher"` populated for recent versions. |
+| **npm provenance attestations** | Every published tarball ships a [Sigstore provenance attestation](https://docs.npmjs.com/generating-provenance-statements) cryptographically linking the tarball to the exact GitHub Actions run that built it. | `npm audit signatures` (run inside any project that depends on `@mushi-mushi/*`) reports `verified registry signatures` and `verified attestations`. The npm web UI shows a "Built and signed on GitHub Actions" badge on each version. |
+| **Pre-publish workspace-protocol guard** | Aborts the publish if `workspace:*` ranges leaked into the tarball (the bug class behind the v0.1.0 incident). | `scripts/check-workspace-protocol.mjs` runs before `changeset publish` in `pnpm release`. |
+| **Post-publish tarball verification** | Re-downloads each just-published tarball and asserts it doesn't contain `workspace:*`. | See the "Verify published tarballs do not contain workspace:*" step in `release.yml`. |
+| **Post-publish `npm audit signatures`** | Re-installs each published version and validates registry signatures + provenance against npm's transparency log. | See the "Audit signatures of installed dependencies" step in `release.yml`. |
+
+### Build-time controls
+
+| Control | What it does |
+|---|---|
+| **All third-party GitHub Actions pinned to commit SHAs** | Every `uses:` in every workflow under `.github/workflows/` is pinned to a 40-character commit SHA with a version comment. Floating tags (`@v4`, `@main`) are mutable and were the entry point for the [tj-actions/changed-files compromise (CVE-2025-30066)](https://github.com/step-security/harden-runner#detected-attacks). |
+| **Harden-Runner egress audit on every job** | [step-security/harden-runner](https://github.com/step-security/harden-runner) records every outbound network call, file write, and process spawn on every CI runner. Detects exfiltration attempts in real time — caught the tj-actions, NX, Shai-Hulud, and Axios attacks for other projects. |
+| **OpenSSF Scorecard** | Weekly + on-push score of the repo's security posture (Pinned-Dependencies, Token-Permissions, Branch-Protection, Code-Review, Dangerous-Workflow, Maintained, SAST, Security-Policy, Signed-Releases, Vulnerabilities). Public results at [scorecard.dev](https://scorecard.dev/viewer/?uri=github.com/kensaurus/mushi-mushi). |
+| **Server-side secret scan (Gitleaks)** | Every PR and every push to `master` runs Gitleaks across the diff / full tree. Belt-and-suspenders to the local pre-commit hook (`scripts/check-no-secrets.mjs`) which can be bypassed with `--no-verify`. |
+| **Local pre-commit secret scanner** | `scripts/check-no-secrets.mjs` runs as a git hook installed by `pnpm install`, blocking commits that look like AWS / Stripe / GitHub / Anthropic / OpenAI / Slack / Supabase keys. |
+| **CodeQL `security-extended`** | Semantic analysis of every TypeScript / JavaScript change finds injection sinks, taint flows, prototype pollution, etc. Runs on every PR, push, and weekly cron. |
+| **Dependency review on PRs** | `actions/dependency-review-action` blocks the PR if it adds or upgrades a dep with a high-severity advisory. |
+| **`pnpm audit --prod --audit-level=high`** | Weekly cron + every push to `master` fails on any high/critical advisory in production deps. |
+
+### Install-time controls (protect the project's own dependency graph)
+
+| Control | What it does |
+|---|---|
+| **`min-release-age` (npm) / `minimumReleaseAge` (pnpm)** | Refuses to resolve any dep version published less than 7 days ago. The Axios 1.14.1 / 0.30.4 compromise (Mar 2026) was detected and removed within ~5 hours; Shai-Hulud (Sep 2025) within <12 hours — a 7-day cooldown blocks every publicly-disclosed 2025–2026 npm supply-chain attack outright. |
+| **`strictDepBuilds: true`** | Fails the install if any transitive dep tries to run a `postinstall` hook the workspace hasn't pre-approved (`onlyBuiltDependencies` allow-list). |
+| **`blockExoticSubdeps: true`** | Refuses to resolve transitive deps from git URLs, tarball URLs, or filesystem paths — anything that didn't go through the npm registry's signing pipeline. |
+| **Dependabot with cooldown** | Routine dep upgrades wait 7 days; security advisories bypass the cooldown automatically. |
+| **`pnpm audit signatures`-style verification** | The release pipeline re-runs `npm audit signatures` against each published version after the publish, with `--audit-level=high`. |
+
+### Verifying a Mushi Mushi tarball before installing
+
+```bash
+# 1. Check provenance attestation matches the public GitHub Actions run
+npm view @mushi-mushi/core --json | jq '.signatures, .dist'
+
+# 2. Inside your own project after install
+npm audit signatures
+
+# Expected: every @mushi-mushi/* package reports
+#   "verified registry signature"
+#   "verified attestation"
+```
+
+If `npm audit signatures` reports any `@mushi-mushi/*` package as unsigned
+or with an invalid attestation, **stop the install and email
+kensaurus@gmail.com immediately** — that's the symptom of either a
+registry compromise or a tampered tarball, and we want to know within
+hours, not days.
+
+### What this hardening does NOT cover
+
+- **Self-hosted deployments.** Once the package is on your machine, the
+  security of your `node_modules`, build pipeline, and runtime is your
+  responsibility. The hardening above protects the path from source to
+  registry; it cannot protect a tarball after it has been downloaded.
+- **Compromise of `kensaurus@gmail.com`.** A trusted-publisher rule still
+  lets the legitimate maintainer publish from any branch they push. If
+  you find yourself with admin access to this repo, treat
+  `.github/workflows/release.yml` as a tier-0 secret.
+- **First-party bugs.** Provenance proves *who* built the tarball and
+  *when*; it does not prove the code is bug-free. CodeQL + tests cover
+  that surface, but no automation catches everything — please continue
+  to report issues to the address above.