@mushi-mushi/core 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

@@ -7,7 +7,7 @@ Core types, API client, and utilities for the Mushi Mushi SDK.
 ## What's Inside
 
 - **Types**: `MushiConfig`, `MushiReport`, `MushiEnvironment`, and all shared interfaces
-- **API Client**: Fetch-based HTTP client with retry and exponential backoff
+- **API Client**: Fetch-based HTTP client with retry and exponential backoff. Tags every internal request with `X-Mushi-Internal: <kind>` so framework SDKs can filter their own traffic out of network capture and `apiCascade`. Ships HMAC-signed reporter helpers (`getLatestSdkVersion`, `listReporterReports`, `listReporterComments`, `replyToReporterReport`) for the two-way reply pipeline
 - **Pre-Filter**: On-device Stage 0 spam/gibberish filter (runs client-side, zero server cost)
 - **Offline Queue**: IndexedDB-backed queue with auto-sync on reconnect
 - **Environment Capture**: Browser/device snapshot (viewport, user agent, connection info)
@@ -15,10 +15,35 @@ Core types, API client, and utilities for the Mushi Mushi SDK.
 - **Session ID**: Tab-scoped session correlation
 - **Rate Limiter**: Token bucket self-throttle to prevent API flooding
 
+## Public types added in 0.7 → 0.11
+
+| Type                       | Purpose                                                                                       |
+|----------------------------|-----------------------------------------------------------------------------------------------|
+| `MushiPreset`              | `'production-calm' \| 'beta-loud' \| 'internal-debug' \| 'manual-only'` posture bundles.      |
+| `MushiWidgetAnchor`        | Raw-CSS positioning (`top` / `right` / `bottom` / `left`) for the widget launcher.            |
+| `MushiPrivacyConfig`       | `maskSelectors`, `blockSelectors`, `allowUserRemoveScreenshot` for screenshot redaction.       |
+| `MushiUrlMatcher`          | `string \| RegExp` element used by `capture.ignoreUrls` and `apiCascade.ignoreUrls`.          |
+| `MushiApiCascadeConfig`    | Object form of `proactive.apiCascade` so URL filters can be declared per-host-app.            |
+| `MushiDiagnosticsResult`   | Return shape of `Mushi.diagnose()` (CSP, runtime-config, capture, widget health).             |
+| `MushiSdkVersionInfo`      | Response shape for `getLatestSdkVersion(packageName)`; powers the outdated-banner UI.         |
+| `MushiTimelineEntry`       | `{ ts, kind: 'route' \| 'click' \| 'request' \| 'log' \| 'screen', payload }` repro entries. |
+| `MushiReporterReport`      | Reporter-facing report row (HMAC-authed) with `unread_count` for the widget badge.            |
+| `MushiReporterComment`     | Reporter-facing comment row (HMAC-authed) tagged `author_kind: 'admin' \| 'reporter'`.        |
+
+Constants: `MUSHI_INTERNAL_HEADER` (`'X-Mushi-Internal'`),
+`MUSHI_INTERNAL_INIT_MARKER`, and the `MushiInternalRequestKind` literal union
+are re-exported so framework adapters can build their own self-noise filters.
+
 ## Usage
 
 ```typescript
-import { createApiClient, createPreFilter, captureEnvironment, createRateLimiter } from '@mushi-mushi/core';
+import {
+  createApiClient,
+  createPreFilter,
+  captureEnvironment,
+  createRateLimiter,
+  MUSHI_INTERNAL_HEADER,
+} from '@mushi-mushi/core';
 ```
 
 This package is used internally by `@mushi-mushi/web` and `@mushi-mushi/react`. Most consumers should use those packages instead.

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.

package/dist/index.cjs

@@ -2,6 +2,8 @@
 
 // src/api-client.ts
 var DEFAULT_API_ENDPOINT = "https://dxptnwrhwsqckaftyymj.supabase.co/functions/v1/api";
+var MUSHI_INTERNAL_HEADER = "X-Mushi-Internal";
+var MUSHI_INTERNAL_INIT_MARKER = "__mushiInternal";
 var DEFAULT_TIMEOUT = 1e4;
 var DEFAULT_MAX_RETRIES = 2;
 function createApiClient(options) {
@@ -13,7 +15,7 @@ function createApiClient(options) {
     maxRetries = DEFAULT_MAX_RETRIES
   } = options;
   let baseUrl = apiEndpoint.replace(/\/$/, "");
-  async function request(method, path, body, retries = maxRetries) {
+  async function request(method, path, body, retries = maxRetries, internalKind) {
     const url = `${baseUrl}${path}`;
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(), timeout);
@@ -23,10 +25,12 @@ function createApiClient(options) {
         headers: {
           "Content-Type": "application/json",
           "X-Mushi-Api-Key": apiKey,
-          "X-Mushi-Project": projectId
+          "X-Mushi-Project": projectId,
+          ...internalKind ? { [MUSHI_INTERNAL_HEADER]: internalKind } : {}
         },
         body: body ? JSON.stringify(body) : void 0,
-        signal: controller.signal
+        signal: controller.signal,
+        ...internalKind ? { [MUSHI_INTERNAL_INIT_MARKER]: internalKind } : {}
       });
       clearTimeout(timer);
       if (response.status === 307 || response.status === 308) {
@@ -35,7 +39,7 @@ function createApiClient(options) {
           const targetBase = target.replace(/\/v1\/.*$/, "").replace(/\/$/, "");
           if (targetBase !== baseUrl) {
             baseUrl = targetBase;
-            return request(method, path, body, retries - 1);
+            return request(method, path, body, retries - 1, internalKind);
           }
         }
       }
@@ -43,7 +47,7 @@ function createApiClient(options) {
         const errorBody = await response.json().catch(() => ({}));
         if (response.status >= 500 && retries > 0) {
           await sleep(getBackoffDelay(maxRetries - retries));
-          return request(method, path, body, retries - 1);
+          return request(method, path, body, retries - 1, internalKind);
         }
         return {
           ok: false,
@@ -60,7 +64,7 @@ function createApiClient(options) {
       clearTimeout(timer);
       if (retries > 0 && isRetryable(error)) {
         await sleep(getBackoffDelay(maxRetries - retries));
-        return request(method, path, body, retries - 1);
+        return request(method, path, body, retries - 1, internalKind);
       }
       return {
         ok: false,
@@ -71,18 +75,87 @@ function createApiClient(options) {
       };
     }
   }
+  async function requestForReporter(method, path, reporterToken, body) {
+    const tokenHash = await sha256Hex(reporterToken);
+    const ts = String(Date.now());
+    const hmac = await hmacSha256Hex(apiKey, `${projectId}.${ts}.${tokenHash}`);
+    const url = `${baseUrl}${path}`;
+    const response = await fetch(url, {
+      method,
+      headers: {
+        "Content-Type": "application/json",
+        "X-Mushi-Api-Key": apiKey,
+        "X-Mushi-Project": projectId,
+        [MUSHI_INTERNAL_HEADER]: "reporter-poll",
+        "X-Reporter-Token-Hash": tokenHash,
+        "X-Reporter-Ts": ts,
+        "X-Reporter-Hmac": hmac
+      },
+      body: body ? JSON.stringify(body) : void 0,
+      [MUSHI_INTERNAL_INIT_MARKER]: "reporter-poll"
+    });
+    if (!response.ok) {
+      const errorBody = await response.json().catch(() => ({}));
+      return {
+        ok: false,
+        error: {
+          code: `HTTP_${response.status}`,
+          message: errorBody.error?.message ?? errorBody.message ?? `HTTP ${response.status} error`
+        }
+      };
+    }
+    const payload = await response.json();
+    return { ok: true, data: payload.data ?? payload };
+  }
   return {
     async submitReport(report) {
-      return request("POST", "/v1/reports", report);
+      return request("POST", "/v1/reports", report, maxRetries, "report-submit");
     },
     async getReportStatus(reportId) {
-      return request("GET", `/v1/reports/${reportId}/status`);
+      return request("GET", `/v1/reports/${reportId}/status`, void 0, maxRetries, "report-status");
     },
     async getSdkConfig() {
-      return request("GET", "/v1/sdk/config");
+      return request("GET", "/v1/sdk/config", void 0, maxRetries, "sdk-config");
+    },
+    async getLatestSdkVersion(packageName) {
+      const query = new URLSearchParams({ package: packageName }).toString();
+      return request("GET", `/v1/sdk/latest-version?${query}`, void 0, maxRetries, "sdk-config");
+    },
+    async listReporterReports(reporterToken) {
+      return requestForReporter("GET", "/v1/reporter/reports", reporterToken);
+    },
+    async listReporterComments(reportId, reporterToken) {
+      return requestForReporter(
+        "GET",
+        `/v1/reporter/reports/${reportId}/comments`,
+        reporterToken
+      );
+    },
+    async replyToReporterReport(reportId, reporterToken, body) {
+      return requestForReporter(
+        "POST",
+        `/v1/reporter/reports/${reportId}/reply`,
+        reporterToken,
+        { body }
+      );
     }
   };
 }
+async function sha256Hex(value) {
+  const buffer = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(value));
+  return Array.from(new Uint8Array(buffer)).map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+async function hmacSha256Hex(secret, value) {
+  const key = await crypto.subtle.importKey(
+    "raw",
+    new TextEncoder().encode(secret),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"]
+  );
+  const buffer = await crypto.subtle.sign("HMAC", key, new TextEncoder().encode(value));
+  return Array.from(new Uint8Array(buffer)).map((b) => b.toString(16).padStart(2, "0")).join("");
+}
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
@@ -776,7 +849,7 @@ function collectInputs() {
     hardwareConcurrency: nav?.hardwareConcurrency
   };
 }
-async function sha256Hex(input) {
+async function sha256Hex2(input) {
   if (typeof crypto !== "undefined" && crypto.subtle) {
     const buf = new TextEncoder().encode(input);
     const digest = await crypto.subtle.digest("SHA-256", buf);
@@ -796,7 +869,7 @@ async function getDeviceFingerprintHash() {
   }
   const inputs = collectInputs();
   const serialised = JSON.stringify(inputs);
-  const hash = await sha256Hex(serialised);
+  const hash = await sha256Hex2(serialised);
   if (typeof localStorage !== "undefined") {
     try {
       localStorage.setItem(CACHE_KEY, hash);
@@ -933,6 +1006,8 @@ function scrubPii(text, config) {
 }
 
 exports.DEFAULT_API_ENDPOINT = DEFAULT_API_ENDPOINT;
+exports.MUSHI_INTERNAL_HEADER = MUSHI_INTERNAL_HEADER;
+exports.MUSHI_INTERNAL_INIT_MARKER = MUSHI_INTERNAL_INIT_MARKER;
 exports.REGION_ENDPOINTS = REGION_ENDPOINTS;
 exports.captureEnvironment = captureEnvironment;
 exports.createApiClient = createApiClient;