Files
Sable/docs/SENTRY_PRIVACY.md
T

341 lines
17 KiB
Markdown

# Sentry Privacy Policy
This document describes exactly what data the Sentry integration collects, what
is masked or blocked, and where the relevant code lives. For setup and
configuration details see [SENTRY_INTEGRATION.md](./SENTRY_INTEGRATION.md).
---
## What Is Collected
Sentry is **disabled by default when no DSN is configured** and can be **opted
in to by users** at any time via Settings → General → Diagnostics & Privacy.
### First-Login Consent Notice
When Sentry is configured, the app shows a dismissible notice the first time a
user loads Sable. The notice explains that crash reporting is available and
provides a one-click opt-in before any data is sent.
| Action | Effect |
| -------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| **"Enable"** | Sentry enabled (`sable_sentry_enabled = 'true'`), page reloads so Sentry initialises — data collection begins after reload |
| **"No thanks"** or **✕ dismiss** | Preference saved as opted-out (`sable_sentry_enabled = 'false'`); notice does not appear again; no Sentry data is ever sent |
The preference persists in `localStorage` and can be changed at any time in
**Settings → General → Diagnostics & Privacy**.
**Code:** `src/app/components/telemetry-consent/TelemetryConsentBanner.tsx`
When enabled, the following categories of data are sent:
### Error Reports
- Exception type and stack trace (function names, file names, line numbers)
- Error message text — scrubbed of tokens and Matrix IDs before sending (see
[What Is Scrubbed](#what-is-scrubbed))
- Browser and OS name/version
- JavaScript engine version
- Application release version (`VITE_APP_VERSION`)
- Sentry environment tag (`VITE_SENTRY_ENVIRONMENT`)
- Current URL path — tokens in query strings are redacted before sending
**Code:** `src/instrument.ts` — `beforeSend` callback
### Breadcrumbs (Action Trail)
Leading up to an error, Sentry records a trail of recent user actions:
- Navigation events (route changes)
- `console.error` and `console.warn` calls — filtered for sensitive patterns
before sending
- Internal debug log entries (category, level, summary message) — filtered
before sending
Breadcrumbs containing any of the patterns listed in
[What Is Scrubbed](#what-is-scrubbed) are sanitised in-place before leaving the
browser.
**Code:** `src/instrument.ts` — `beforeBreadcrumb` callback
**Code:** `src/app/utils/debugLogger.ts` — Sentry breadcrumb integration
### Application Breadcrumbs
In addition to automatic navigation/console breadcrumbs, the following named
events are explicitly recorded as breadcrumbs:
| Event | Category | Level | Source |
| ------------------------------------------- | -------- | ------------- | ------------------------- |
| Session forcibly logged out by server | `auth` | warning | `ClientRoot.tsx` |
| Sync state changed to Reconnecting/Error | `sync` | warning/error | `SyncStatus.tsx` |
| Sliding sync first run completed | `sync` | info | `initMatrix.ts` |
| Crypto store mismatch — wiping local stores | `crypto` | warning | `initMatrix.ts` |
| Key backup failed | `crypto` | error | `useKeyBackup.ts` |
| High media inflight request count | `media` | warning | `ClientNonUIFeatures.tsx` |
**Code:** `src/app/pages/client/ClientRoot.tsx`, `src/app/pages/client/SyncStatus.tsx`,
`src/client/initMatrix.ts`, `src/app/hooks/useKeyBackup.ts`,
`src/app/pages/client/ClientNonUIFeatures.tsx`
### Component Error Capture
The following failure paths use explicit `captureException` because they are
caught by state management hooks and never propagate to React's ErrorBoundary:
| Failure | Tag | Source |
| ---------------------------------------------- | ------------------------------------ | ----------------------------- |
| Client failed to load (fetch/init) | `phase: load` | `ClientRoot.tsx` |
| Client failed to start (sync start) | `phase: start` | `ClientRoot.tsx` |
| Background notification client failed to start | `component: BackgroundNotifications` | `BackgroundNotifications.tsx` |
**Code:** `src/app/pages/client/ClientRoot.tsx`,
`src/app/pages/client/BackgroundNotifications.tsx`
### Performance Traces
- Timing of React Router navigations (page-load and route-change latency)
- Custom spans for Matrix sync cycles, message send, and room data loading
- JavaScript CPU profiles during traced transactions (call-stack samples)
Performance data contains **no message content, no room names, and no user
identifiers**. Spans are labelled with operation names only.
| Span name | Operation | Source |
| ----------------------- | ----------------- | ---------------------- |
| `auth.login` | `auth` | `loginUtil.ts` |
| `decrypt.event` | `matrix.crypto` | `EncryptedContent.tsx` |
| `decrypt.bulk` | `matrix.crypto` | `room.ts` |
| `timeline.jump_load` | `matrix.timeline` | `RoomTimeline.tsx` |
| `message.send` | `matrix.message` | `RoomInput.tsx` |
| Sliding sync processing | `matrix.sync` | `slidingSync.ts` |
**Sample rates:**
| Environment | Traces | Profiles |
| ------------------------- | ------ | -------- |
| `production` | 10% | 10% |
| `preview` / `development` | 100% | 100% |
**Code:** `src/instrument.ts` — `tracesSampleRate`, `profilesSampleRate`
**Code:** `src/app/features/room/RoomInput.tsx` — message send span
**Code:** `src/app/utils/room.ts`, `src/client/slidingSync.ts` — room/sync spans
### Custom Metrics
All metrics contain no message content, room names, or user identifiers.
Attribute values are limited to short enumerated strings (error codes, states)
or numeric measurements.
#### Authentication
| Metric | Type | Attributes | What it tracks |
| ------------------------- | ----- | ---------- | ------------------------------------ |
| `sable.auth.login_failed` | count | `errcode` | Login attempt failures by error code |
**Code:** `src/app/pages/auth/login/loginUtil.ts`
#### Cryptography
| Metric | Type | Attributes | What it tracks |
| ----------------------------------- | ------------ | ----------------------------------- | ------------------------------------------------ |
| `sable.decryption.failure` | count | `reason` | Unable-to-decrypt events by failure reason |
| `sable.decryption.event_ms` | distribution | — | Per-event decryption latency |
| `sable.decryption.bulk_latency_ms` | distribution | `event_count` | Bulk re-decryption time on room open |
| `sable.crypto.key_backup_failures` | count | `errcode` | Key backup errors by code |
| `sable.crypto.store_wipe` | count | — | Crypto store mismatch wipe-and-retry occurrences |
| `sable.crypto.verification_outcome` | count | `outcome` (`completed`/`cancelled`) | E2E device verification outcomes |
**Code:** `src/app/features/room/message/EncryptedContent.tsx`,
`src/app/utils/room.ts`, `src/app/hooks/useKeyBackup.ts`,
`src/client/initMatrix.ts`, `src/app/components/DeviceVerification.tsx`
#### Messaging
| Metric | Type | Attributes | What it tracks |
| ------------------------------- | ------------ | ----------- | ----------------------------------- |
| `sable.message.send_latency_ms` | distribution | `encrypted` | Message send round-trip time |
| `sable.message.send_error` | count | — | Send errors from message composer |
| `sable.message.send_failed` | count | — | Local-echo `NOT_SENT` status events |
**Code:** `src/app/features/room/RoomInput.tsx`,
`src/app/features/room/RoomTimeline.tsx`
#### Timeline
| Metric | Type | Attributes | What it tracks |
| ------------------------------ | ------------ | ----------- | -------------------------------- |
| `sable.timeline.open` | count | `mode` | Timeline render initiations |
| `sable.timeline.render_window` | distribution | `mode` | Initial virtual window size |
| `sable.timeline.jump_load_ms` | distribution | — | Event-jump timeline load latency |
| `sable.timeline.reinit` | count | — | Full timeline re-initialisations |
| `sable.pagination.error` | count | `direction` | Pagination errors by direction |
**Code:** `src/app/features/room/RoomTimeline.tsx`
#### Sync
| Metric | Type | Attributes | What it tracks |
| --------------------------------- | ------------ | ---------------------------- | -------------------------------------- |
| `sable.sync.transport` | count | `type` (`sliding`/`classic`) | Sync transport type used |
| `sable.sync.cycle` | count | (various) | Completed sliding sync cycles |
| `sable.sync.error` | count | `errcode` | Sliding sync errors |
| `sable.sync.initial_ms` | distribution | — | Initial sync completion time |
| `sable.sync.processing_ms` | distribution | — | Per-cycle sync processing time |
| `sable.sync.lists_loaded_ms` | distribution | — | Time for room lists to fully load |
| `sable.sync.total_rooms` | gauge | `sync_type` | Total rooms known at list load |
| `sable.sync.active_subscriptions` | gauge | — | Active room subscription count |
| `sable.sync.client_ready_ms` | distribution | `type` | Time from init to client ready |
| `sable.sync.time_to_ready_ms` | distribution | — | Wall-clock time to first sync ready |
| `sable.sync.degraded` | count | `state` | Sync reconnect/error state transitions |
**Code:** `src/client/initMatrix.ts`, `src/client/slidingSync.ts`,
`src/app/pages/client/ClientRoot.tsx`, `src/app/pages/client/SyncStatus.tsx`
#### Media
| Metric | Type | Attributes | What it tracks |
| ------------------------------- | ------------ | ---------- | ---------------------------- |
| `sable.media.upload_latency_ms` | distribution | `mimetype` | Media upload round-trip time |
| `sable.media.upload_bytes` | distribution | `mimetype` | Upload size distribution |
| `sable.media.upload_error` | count | `reason` | Upload failures by reason |
| `sable.media.blob_cache_size` | gauge | — | Blob URL cache entry count |
| `sable.media.inflight_requests` | gauge | — | Concurrent media requests |
**Code:** `src/app/utils/matrix.ts`, `src/app/pages/client/ClientNonUIFeatures.tsx`
#### Background clients & debug telemetry
| Metric | Type | Attributes | What it tracks |
| ------------------------------- | ----- | ---------- | -------------------------------------- |
| `sable.background.client_count` | gauge | — | Active background notification clients |
| `sable.errors` | count | `category` | Error-level debug log entries |
| `sable.warnings` | count | `category` | Warning-level debug log entries |
**Code:** `src/app/pages/client/BackgroundNotifications.tsx`,
`src/app/utils/debugLogger.ts`
### Session Replay _(opt-in, disabled by default)_
When session replay is explicitly enabled by the user, Sentry records UI
interactions to help reproduce bugs. **All content is masked at the browser
level before any data leaves the device:**
- All text on screen → replaced with `█` characters
- All images, video, and audio → blocked entirely (replaced with a grey box)
- All form inputs, including the message composer → replaced with `*` characters
This means **no Matrix messages, no room names, no user display names, and no
media are ever visible in a replay**.
Sample rates for replay:
| Trigger | Production | Preview / Dev |
| -------------------- | ---------- | ------------- |
| Regular sessions | 10% | 100% |
| Sessions with errors | 100% | 100% |
**Code:** `src/instrument.ts` — `replayIntegration` call with `maskAllText`,
`blockAllMedia`, `maskAllInputs`
### Bug Reports _(manual, opt-in per report)_
When a user submits a bug report via `/bugreport` or the "Bug Report" button:
- Free-text description written by the user
- Optional: recent debug log entries (last 100) attached as a file
- Platform info, browser version, application version
- Checkbox to send or not send to Sentry is **shown before submission**
**Code:** `src/app/features/bug-report/BugReportModal.tsx`
---
## What Is Never Collected
- Matrix message content
- Room names or aliases
- User display names or avatars
- Contact lists or room member lists
- Encryption keys or session data
- IP addresses (`sendDefaultPii: false`)
- Authentication tokens (scrubbed — see below)
---
## What Is Scrubbed
All scrubbing happens **in the browser before data is transmitted**. Nothing
leaves the device in unredacted form.
### Tokens and Credentials
The following patterns are replaced with `[REDACTED]` in error messages,
exception values, breadcrumb messages, and request URLs:
- `access_token`
- `password`
- `token`
- `refresh_token`
- `session_id`
- `sync_token`
- `next_batch`
- HTTP `Authorization` headers
**Code:** `src/instrument.ts` — `beforeSend` and `beforeBreadcrumb` callbacks
Regex: `/(access_token|password|token|refresh_token|session_id|sync_token|next_batch)([=:]\s*)([^\s&]+)/gi`
### Matrix Identifiers
Matrix IDs are replaced with placeholder tokens before sending:
| Original form | Replaced with |
| -------------- | ------------- |
| `@user:server` | `@[USER_ID]` |
| `!room:server` | `![ROOM_ID]` |
| `$event_id` | `$[EVENT_ID]` |
**Code:** `src/instrument.ts` — `beforeSend` callback (applied to `event.message`
and all `event.exception.values`)
---
## User Controls
Users can adjust Sentry behaviour without restarting the app:
| Setting | Location | `localStorage` key | Default |
| ----------------------------- | ---------------------------------------------------------------------------- | ---------------------------------- | ----------------- |
| Disable Sentry entirely | Settings → General → Diagnostics & Privacy | `sable_sentry_enabled` | Enabled |
| Enable session replay | Settings → General → Diagnostics & Privacy | `sable_sentry_replay_enabled` | Disabled (opt-in) |
| Disable breadcrumb categories | Settings → Developer Tools → Error Tracking (Sentry) → Breadcrumb Categories | `sable_sentry_breadcrumb_disabled` | All enabled |
**Rate limiting:** A maximum of 50 error events are forwarded to Sentry per page load (session).
Subsequent errors are silently dropped, protecting against quota exhaustion without affecting
in-app behaviour. Performance traces are not subject to this cap.
Changes to Sentry enable/disable and session replay take effect after the next page refresh
(the SDK is initialised once at startup). Breadcrumb category changes take effect immediately.
**Code:** `src/instrument.ts` — reads `localStorage` before `Sentry.init()`, enforces rate limit in `beforeSend`
**Code:** `src/app/features/settings/developer-tools/SentrySettings.tsx` — settings UI
**Code:** `src/app/utils/debugLogger.ts` — per-category breadcrumb filtering and session stats
---
## Data Residency
Sentry data is sent to the Sentry.io cloud service. The destination project is
configured by the operator via `VITE_SENTRY_DSN`. Self-hosted Sentry instances
are supported by changing the DSN.
When `VITE_SENTRY_DSN` is not set, the integration is entirely inactive — no
code path in the Sentry SDK is reached and no data is transmitted.
---
## Further Reading
- [SENTRY_INTEGRATION.md](./SENTRY_INTEGRATION.md) — setup, configuration, environment variables, and deployment instructions
- [Sentry Privacy Policy](https://sentry.io/privacy/) — Sentry's own data handling commitments
- [Sentry Session Replay privacy documentation](https://docs.sentry.io/product/explore/session-replay/privacy/) — details on masking and blocking behaviour